Technical Guide

Beginning in Launcher 3.x, the configurations for the authentication providers have been moved out of the 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 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, 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 "https://us-central1-bluefletch-ems.cloudfunctions.net/launcherRedirect/auth". Starting in Auth4, the redirect callback URL should be com.bluefletch.ems.auth://callback

redirect_url_verify

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

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 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/<tenant_id>", where <tenant_id> 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": "<client_id during registration>",
    "authorization_user_agent": "DEFAULT",
    "redirect_uri": "msauth://com.bluefletch.ems.auth.msal/KUKEusfKtqAOu9UB6jgjtTMKYas=",
    "authority_type": "AAD",
    "authority_url": "https://login.microsoftonline.com/<tenant_id>",
    "tenant_id": "<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

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/<audience_tenant_id>", where <audience_tenant_id> 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 and 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": "<client_id during registration>",
    "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>",
    "audience_tenant_id" : "<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 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\"]"
}
...

PreviousAlternate Secondary Authentication NextLDAP

Last updated 9 days ago