# Technical Guide Beginning in Launcher 3.x, the configurations for the authentication providers have been moved out of the [`settings`](https://docs.bluefletch.com/bluefletch-enterprise/bluefletch-launcher/technical-guide#settings) object into their own separate objects under the root configuration. If you are using Launcher 3.x, the following should be used when configuring the authentication providers: ### LDAP | Field | Description | | -------- | --------------------------------------------------------------------------------------------------------------- | | hostname | **string** Hostname of the LDAP server. | | port | **integer** Port of the LDAP server. | | domain | **string** The domain of the user when logging in (i.e. `"@BLUEFLETCH"`). | | rootDN | **string** The Root DN of where the users can be searched after authentication (e.g. `"DC=BLUEFLETCH,DC=com"`). | | useHttps | **boolean** Set to true to use LDAPS when authenticating via HTTPS. | **Example:** ``` ... "auth_ldap": { "hostname" : "ldapserver.bluefletch.com", "port" : 636, "domain" : "@BLUEFLETCH", "rootDN" : "DC=BLUEFLETCH,DC=com", "useHttps" : true } ... ``` #### Auth4 LDAP Auth version 4 LDAP supports all original LDAP key-value pairs, and beginning in Auth version 4.7.14 additional attributes can be added to the base configuration. | Field | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | auth\_default\_group | **string** If specified, Auth will always assign an authenticated user this string value as a session group upon login. | | generateToken | **boolean** If `true`, Auth module will generate a unique JWT token corresponding to the authenticating user. This will also require that a signing certificate be imported into Auth. Default is `false`. | | keyAlias | **string** If generating a token, this value is the provided 'name' when the certificate is created prior to importing into Auth. Only required if `generateToken` is `true`. | | claimsMap | **string** If generating a token, specify a comma-delimited list of LDAP attributes to be added as claims inside the JWT token. Only required if `generateToken` is `true`. | **Optional: LDAP Connections Array** Beginning in Auth - LDAP version 4.7.14, LDAP supports listing multiple LDAP domain/connection point objects, using the same key-values listed above, within an `auth_ldap_connections` array. This will give several authentication options in case one service is unavailable. The authentication module will attempt each service until it successfully logs a user in with the provided credentials. **Auth4 LDAP Example (including optional `auth_ldap_connections`):** ``` ... "auth_ldap": { "hostname": "ldapserver.bluefletch.com", "port": 636, "domain": "@BLUEFLETCH", "rootDN": "DC=BLUEFLETCH,DC=com", "useHttps": true, "auth_default_group": "Associates", "keyAlias": "aliasNameForKey", "generateToken": true, "claimsMap": "sam=sAMAccountName,cname=cn,upn=userPrincipalName,memberof=memberOf,dn=distinguishedName" }, "auth_ldap_connections" : [ { "hostname": "ldapserver.mnl.bluefletch.com", "port": 389, "domain": "@MNL", "rootDN": "DC=BLUEFLETCH,DC=com", "useHttps": false }, { "hostname": "ldapserver.atl.bluefletch.com", "port": 636, "domain": "@ATL", "rootDN": "DC=BLUEFLETCH,DC=com", "useHttps": true } ] ... ``` ### Okta/OneLogin (PKCE flow) | Field | Description | | ------------- | -------------------------------------------------------------------------------------------------------- | | issuer\_uri | **string** The configured issuer URI for the identity provider. | | client\_id | **string** The configured client ID for this application. | | redirect\_uri | **string** The configured redirect callback URI for this application. | | scopes | **string** The scopes where this authentication applies. | | force\_logout | **string** This allows for overriding the default logout End Session URL. This is required for OneLogin. | The following fields will still need to be configured under the `settings` object when using the Okta Auth Provider: | Field | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | auth\_location\_field | **string** An optional setting that tells authorization which field in the auth provider response contains location information. Used in conjunction with `auth_location_regex`. | | auth\_location\_regex | **string** A regular expression to extract the location value from the location field. Used in conjunction with `auth_location_field`. | | auth\_group\_field | **string** An optional setting that tells authorization which field in the authentication provider response contains group information. Used in conjunction with `auth_group_regex`. | | auth\_group\_regex | **string** A regular expression to match against the group information. Used in conjunction with `auth_group_field`. | | auth\_group\_regex\_true | **string** If the regular expression `auth_group_regex` returns `true` (found a value), will use this group value. | | auth\_default\_group | **string** A default group. | | auth\_role\_field | **string** An optional setting that tells authorization which field in the authentication provider response contains user role information. Used in conjunction with `auth_role_regex`. Available in Auth 1.1.x. | | auth\_role\_regex | **string** A regular expression to match against the role information. Used in conjunction with `auth_role_field`. | | auth\_role\_regex\_true | **string** If the regular expression `auth_role_regex` returns `true` (found a value), will use this role value. | | auth\_default\_role | **string** A default user role. | **Example:** ``` ... "auth_okta": { "issuer_uri" : "https://dev.oktapreview.com", "client_id" : "0o5o9hn89wN4AAhhJ0h7", "redirect_uri" : "com.bluefletch.launcher:/callback", "scopes" : "[\"openid\", \"profile\", \"offline_access\", \"groups\"]" }, "settings" : { ... "auth_default_group" : "Associates", "auth_group_field" : "title", "auth_group_regex" : "(?i)leader$", "auth_group_regex_true" : "Managers", "auth_location_field" : "custom_fields.deptnum", "auth_location_regex" : "(\\d+)", ... } ... ``` Beginning in Auth 4.x, Okta authentication will be configured with the `auth_oauth2` object instead of the `auth_okta` object, as in this example: ``` "auth_oauth2": { "issuer_url": "https://dev.oktapreview.com", "client_id": "0o5o9hn89wN4AAhhJ0h7", "redirect_url": "com.bluefletch.ems.auth://callback", "browser": "com.bluefletch.ems.browser", "scopes": "openid profile offline_access groups", "logout_redirect": "com.bluefletch.ems.auth://logout" }, ``` > Please note the following changes:\ > \* the `issuer_uri` and `redirect_uri` have been renamed to `issuer_url` and `redirect_url`. \* new redirect URLs have been introduced for compatibility with other OIDC providers: \* `com.bluefletch.ems.auth://callback` \* `com.bluefletch.ems.auth://logout` For more information on the properties for configuring, see the [AppAuth/OIDC IDP](#appauthoidc-idp) section. ### Okta (Session) Beginning in Auth 4.6.1, a REST session flow is supported for authentication through Okta using the `auth_oauth2` object and the OKTAREST Auth binary. | Field | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | issuer\_url | **string** The configured Issuer URI for the identity provider. | | client\_id | **string** The configured client ID for this application. | | redirect\_url | **string** The configured redirect callback URL for this application. Use `"com.bluefletch.ems.auth://callback"`. | | scopes | **string** The scopes where this authentication applies. | | redirect\_url\_verify | **string** Specifies the redirect URL used when refreshing cookies during the verification after reauthentication. Always set the value as `"com.bluefletch.ems.auth://verified"`. Requires the Launcher `settings` configuration to also have `verifyIdpOnReauth` set to `true`. | | mfaVerifyIntervalWait | **integer** Number of seconds to wait before reattempting multi-factor authentication in Okta Verify push. Default is `2`. Introduced in Auth 4.6.2. | | mfaVerifyAttempts | **integer** Maximum number of attempts to correctly verify multi-factor authentication before account locks. Default is `10`. Introduced in Auth 4.6.2. | **Example:** ``` ... "auth_oauth2": { "host_url": "https://dev.oktapreview.com", "client_id": "0o5o9hn89wN4AAhhJ0h7", "redirect_url": "com.bluefletch.ems.auth://callback", "scopes": "openid email profile offline_access groups", "logout_redirect": "com.bluefletch.ems.auth://logout", "mfaVerifyIntervalWait": 5, "mfaVerifyAttempts": 7 } ... ``` ### AppAuth/OIDC IdP Beginning in Auth 4.x, the AppAuth/Generic OAuth2 configuration will support login through the [BlueFletch Browser](https://docs.bluefletch.com/bluefletch-enterprise/product-guides/browser/features), as well as Chrome Custom Tabs. The authenticating browser is defined by the `browser` value. | Field | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | issuer\_url | **string** The configured issuer URL for the identity provider. | | client\_id | **string** The configured client ID for this application. | | redirect\_url |

string The configured redirect callback URL for this application. The recommended callback URL is "com.bluefletch.launcher:/callback". However, if the identity provider only supports HTTPS redirect URLs, use "".
Starting in Auth4, the redirect callback URL should be com.bluefletch.ems.auth://callback

| | redirect\_url\_verify | **string** Specifies the redirect URL used when refreshing cookies during the verification after reauthentication. Always set the value as `"com.bluefletch.ems.auth://verified"`. Requires the Launcher `settings` configuration to also have `verifyIdpOnReauth` set to `true`. | | scopes | **string** The OpenID scope values required for the identity provider. | | baseUrl | **string** Base URL for the identity provider. | | authorize\_url | **string** The full URL for the `authorize` endpoint for the identity provider. | | token\_url | **string** The full URL for the `token` endpoint for the identity provider. | | logout\_url | **string** The full URL for the `logout` endpoint for the identity provider. | | logout\_redirect | **string** The full URL for the logout redirection location for your IdP. Default is `"com.bluefletch.ems.auth://logout"`. | | userinfo\_url | **string** The full URL of the `userInfo` endpoint for the identity provider. | | resource | **string** Specifies the host to access for a token during login when the IdP does not provide it through `userinfo_url`. Used in Azure AD authentication (e.g `"https://graph.microsoft.com"`). | | alternateResource | **string** Specifies an additional resource for which the access token should be valid. By default, Azure generates an encrypted access token for use with Microsoft Graph. By specifying an alternate host, the token becomes a standard access token. (e.g. `https://graph.windows.net` or `api://com.bluefletch.ems.auth`). Available starting version 4.8.17. | | login\_hint | **string** Hint to be displayed for the username field on the identity provider login page. | | ignoreExpiresIn | **boolean** If `true`, instructs the launcher to refresh the token based on the `refreshThresholdInMins` value instead of the expiration indicated in the token. | | browser | **string** Specifies the browser package name to execute the `authorize` call. Default is `"com.android.chrome"`. | | refreshThresholdInMins | **integer** The number of minutes after which the launcher will automatically refresh the token if `ignoreExpiresIn` is set to `true`. | | auth\_location\_field | **string** An optional setting that tells authorization which field in the auth provider response contains location information. Used in conjunction with `auth_location_regex`. | | auth\_location\_regex | **string** A regular expression to extract the location value from the location field. Used in conjunction with `auth_location_field`. | | auth\_group\_field | **string** An optional setting that tells authorization which field in the authentication provider response contains group information. Used in conjunction with `auth_group_regex`. | | auth\_group\_regex | **string** A regular expression to match against the group information. Used in conjunction with `auth_group_field`. | | auth\_group\_regex\_true | **string** If the regular expression `auth_group_regex` returns `true` (found a value), will use this group value. | | auth\_default\_group | **string** A default group. | | auth\_role\_field | **string** An optional setting that tells authorization which field in the authentication provider response contains user role information. Used in conjunction with `auth_role_regex`. Available in Auth 1.1.x. | | auth\_role\_regex | **string** A regular expression to match against the role information. Used in conjunction with `auth_role_field`. | | auth\_role\_regex\_true | **string** If the regular expression `auth_role_regex` returns `true` (found a value), will use this role value. | | auth\_default\_role | **string** A default user role. | | claim\_userId | **string** The claim in the access token that contains the user ID of the logged-in user. | | claim\_username | **string** The claim in the access token that contains the display name of the logged-in user. | | claim\_groups | **string** The claim in the access token that contains the logged-in user's membership groups. | | userinfo\_attrs | **string** A comma-delimited list of names indicating the field names within the `userInfo` response that should be copied into the session extended attributes collection. This provides the ability to get optional data points. | **Example:** ``` ... "auth_oauth2": { "client_id": "com.bluefletch.ems.auth", "redirect_url": "com.bluefletch.launcher:/callback", "baseUrl": "https://oauth2server.bluefletch.com", "authorize_url": "https://oauth2server.bluefletch.com/oauth2/authorize", "token_url": "https://oauth2server.bluefletch.com/oauth2/token", "userinfo_url": "https://oauth2server.bluefletch.com/oauth2/userinfo", "logout_url": "https://oauth2server.bluefletch.com/oauth2/logout", "scopes": "openid profile offline_access groups", "claim_userId": "upn", "claim_username": "commonname", "claim_groups": "memberof", "browser": "com.bluefletch.ems.browser" } ... ``` #### OIDC-Azure Beginning in Auth 4.3.x, the `auth_oauth2` object can be applied to Azure AD authentication when using the OIDC-Azure Auth binary. **Example:** ``` ... "auth_oauth2": { "client_id": "01cceca8-d87b-11ec-9d64-0242ac120002", "redirect_url": "msauth://com.bluefletch.ems.auth/K8s43sSfptA3T2LoAlTd9XEfKQg=", "baseUrl": "https://login.microsoftonline.com/469a2de6-d87b-11ec-9d64-0242ac120002", "authorize_url": "https://login.microsoftonline.com/469a2de6-d87b-11ec-9d64-0242ac120002/oauth2/authorize", "token_url": "https://login.microsoftonline.com/469a2de6-d87b-11ec-9d64-0242ac120002/oauth2/token", "scopes": "openid profile email User.Read GroupMember.Read.All https://graph.microsoft.com", "resource" : "https://graph.microsoft.com", "userinfo_url": "https://graph.microsoft.com/v1.0/me/memberOf", "claim_userId": "upn", "claim_username": "name", "claim_groups": "memberOf" } ... ``` ### MSAL for Azure AD BlueFletch continues to support the following configuration settings for the Auth version 3.x.x binaries of the MSAL module. See [Auth4 MSAL](#auth4-msal) below for configuration settings supported in Auth version 4.5.9 and above. | Field | Description | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | client\_id | **string** The client ID used to register this application. | | authorization\_user\_agent | **string** Set to `"DEFAULT"`. | | redirect\_uri | **string** The configured redirect callback URI for this application. For the MSAL library, the redirect must use the application ID and its signature. Use `"msauth://com.bluefletch.ems.auth.msal/KUKEusfKtqAOu9UB6jgjtTMKYas="`. | | broker\_redirect\_uri\_registered | **boolean** Set to `true` if using the Microsoft Authenticator application in Shared Device Mode on the device. Default is `false`. | | authority\_type | **string** Set to `"AAD"` for Azure AD. | | authority\_url | **string** The directory from which MSAL can request tokens. Typically, set to `"https://login.microsoftonline.com/"`, where `` is the Azure Tenant ID. | | tenant\_id | **string** Set to the Azure Tenant ID. Deprecated as of Auth version 4.5.9 (see Auth4 MSAL). | | logout\_url | **string** Set to `"https://login.microsoftonline.com/common/oauth2/logout?post_logout_redirect_uri=https%3A%2F%2Fwww.office.com%2F%3Fref%3Dlogout"`, which will also log the user out of office365. | | limit\_to\_launcher\_groups | **boolean** If set to `true`, only the groups identified in the group\_inclusion and layouts in the launcher configuration file will be passed into the session. | **Auth3 Example:** ``` ... "auth_msal" : { "client_id": "", "authorization_user_agent": "DEFAULT", "redirect_uri": "msauth://com.bluefletch.ems.auth.msal/KUKEusfKtqAOu9UB6jgjtTMKYas=", "authority_type": "AAD", "authority_url": "https://login.microsoftonline.com/", "tenant_id": "", "logout_url": "https://login.microsoftonline.com/common/oauth2/logout?post_logout_redirect_uri=https%3A%2F%2Fwww.office.com%2F%3Fref%3Dlogout", "limit_to_launcher_groups": true } ... ``` #### Auth4 MSAL Beginning in Auth version 4.5.9, some of the MSAL configuration settings change to more fully support new developments from Microsoft. | Field | Description | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | client\_id | **string** The client ID used to register this application in Azure AD. | | authorization\_user\_agent | **string** Set to `"DEFAULT"`, or set to `"BROWSER"` to use the BlueFletch Browser. Support for BlueFletch Browser introduced in Auth version 4.8.0. | | redirect\_uri | **string** The configured redirect callback URI for this application. For the MSAL library, the redirect must use the application ID and its signature. Use `"msauth://com.bluefletch.ems.auth/KUKEusfKtqAOu9UB6jgjtTMKYas%3D"`. | | authority\_type | **string** Set to `"AAD"` for Azure AD. | | authority\_url | **string** The directory from which MSAL can request tokens. Typically, set to `"https://login.microsoftonline.com/"`, where `` is the Azure Tenant ID. | | logout\_url | **string** Set to `"https://login.microsoftonline.com/common/oauth2/logout?post_logout_redirect_uri=https%3A%2F%2Fwww.office.com%2F%3Fref%3Dlogout"`, which will also log the user out of office365. | | limit\_to\_launcher\_groups | **boolean** If set to `true`, only the groups identified in the [`group_inclusion`](https://docs.bluefletch.com/bluefletch-enterprise/bluefletch-launcher/technical-guide#group-inclusions) and [`layouts`](https://docs.bluefletch.com/bluefletch-enterprise/bluefletch-launcher/technical-guide#layouts) in the launcher configuration file will be passed into the session. | | scopes | **string** OIDC scope values required for the identity provider. For MSAL, the values should be `"openid email profile User.Read GroupMember.Read.All"`. | | audience\_tenant\_id | **string** Set to the Azure Tenant ID. Replaces `tenant_id` starting in Auth version 4.5.9. | | shared\_device\_mode\_supported | **boolean** Set to `true` if using the Microsoft Authenticator application in Shared Device Mode on the device. Default is `false`. | | broker\_redirect\_uri\_registered | **boolean** If `true`, brokered authentication is applied; the Auth module will validate the redirect URI and return an exception if the Auth module is not formatted to communicate with the broker. Set to `true` if using the Microsoft Authenticator application in Shared Device Mode on the device. Default is `false`. | | limit\_groups\_to\_direct\_membership | **boolean** If set to `true`, only direct group membership information will be returned from Azure. If `false`, all inherited/related group information (indentified as `transitiveMemberOf` in Azure) is returned. Default is `false`. Introduced in Auth version 4.7.8. | **Auth4 Example:** ``` ... "auth_msal" : { "client_id": "", "authorization_user_agent" : "DEFAULT", "redirect_uri": "msauth://com.bluefletch.ems.auth/KUKEusfKtqAOu9UB6jgjtTMKYas%3D", "authority_type": "AAD", "authority_url": "https://login.microsoftonline.com/", "audience_tenant_id" : "", "logout_url": "https://login.microsoftonline.com/common/oauth2/logout?post_logout_redirect_uri=https%3A%2F%2Fwww.office.com%2F%3Fref%3Dlogout", "limit_to_launcher_groups": true, "scopes": "openid email profile User.Read GroupMember.Read.All", "shared_device_mode_supported": true, "broker_redirect_uri_registered": true, "limit_groups_to_direct_membership": true } ... ``` For more information on configuring, see the [AppAuth/OIDC IdP](#appauthoidc-idp) section. ### ADFS 3.0/2012 Using ADAL library | Field | Description | | --------------- | -------------------------------------------------------------------------------------- | | authority | **string** Configured resource ID for this application. | | resourceId | **string** Configured resource ID for this application. | | clientId | **string** Configured client ID for this application. | | redirectUri | **string** Configured callback URL for this application | | defaultDomain | **string** Pre-populates the username field with the domain prefix (optional). | | claim\_userId | **string** Passthrough field containing the userID (e.g. `"unique_name"`). | | claim\_username | **string** LDAP passthrough field containing the user's display name. | | claim\_groups | **string** LDAP passthrough field containing the groups (e.g. equivalent to MemberOf). | | baseUrl | **string** The base URL for the ADFS environment. | **Example:** ``` ... "auth_adal" : { "baseUrl" : "https://adfs2012.bluefletch.com", "authority" : "https://adfs2012.bluefletch.com/adfs/oauth2", "clientId" : "com.bluefletch.ems.auth", "resourceId" : "com.bluefletch.ems.auth", "redirectUri" : "com.bluefletch.launcher:/callback", "defaultDomain" : "BLUEFLETCH\\", "claim_userId" : "upn", "claim_username" : "commonname", "claim_groups" : "MemberOf" } ... ``` ### Okta (Resource Owner Flow) | Field | Description | | -------------- | --------------------------------------------------------------------- | | issuer\_uri | **string** The configured Issuer URI for the identity provider. | | client\_id | **string** The configured client ID for this application. | | client\_secret | **string** The configured client secret for this application. | | redirect\_uri | **string** The configured redirect callback URI for this application. | | scopes | **string** The scopes where this authentication applies. | **Example:** ``` ... "auth_oktaRest": { "issuer_uri" : "https://dev.oktapreview.com", "client_id" : "0o5o9hn89wN4AAhhJ0h7", "client_secret" : "A8300hhnadf84993225160kjfdB", "redirect_uri" : "com.bluefletch.launcher:/callback", "scopes" : "[\"openid\", \"profile\", \"offline_access\", \"groups\"]" } ... ```