SSO OKTA - UM 2.0

❗️

This is user management 2.0 documentation

For previous versions, please refer to SSO Okta

SSO & SCIM configuration process

High level steps

• Configuration in Okta for SSO
• Optional configuration in Okta for SCIM (role mapping)
• Configuration in Umbrella

flowchart TD
  
  A[["OKTA SSO"]]-.->A1
  B[["OKTS SCIM"]]-.->B1
  C[["Umbrella"]]-.->C1
  
  subgraph "..."
  	C1["Configure the provider"]
  	C2["Send the certificate"]
  	C3["Optional - Configure the mapper"]
    C1 -.-> C2
  	C2 -.-> C3
  end
  
  subgraph ".."
  	B1["Configure Profile editor"]
  	B2["Configure _Umbrella roles_ attribute"]
  	B3["Assign users to the Umbrella platform"]
  	B1 -.-> B2
  	B2 -.-> B3
  end
  
  subgraph "."
  	A1["Create App"]
    A2["Configure App"]
  	A3["Optional - Configure Direct login from the OKTA App"]
  	A4{{"Send Client ID and Client Secret"}}
  	A1 -.-> A2
  	A2 -.-> A3
  	A3 -.-> A4
  end
  

Detailed steps by Provider

OKTA Using OpenID

1. Access OKTA admin Console.
2. Navigate to Applications > Applications page, and click on Create App Integration.
3. Choose the following for the application:
   • Sign-in methods: OIDC - OpenID Connect
   • Applicate type: Web Application
4. In the App setting enter the following:
   • Sign-in redirect URIs: https://login.umbrellacost.io/auth/realms/{{REALM_ID}}/broker/okta-oidc/endpoint
   • Sign-out redirect URIs: https://login.umbrellacost.io/auth/realms/{REALM_ID}/broker/okta-oidc/endpoint/logout_response
5. (Optional) To allow login directly from the OKTA App, configure the following:
   • Login initiated by: Either Okta or App
   • Application visibility: Display application icon to users
   • Login flow: Redirect to app to initiate login (OIDC Compliant)
   • Initiate login URI: https://login.umbrellacost.io/auth/realms/REALM_ID/protocol/openid-connect/auth?client_id=anodot-cost-login&redirect_uri=https%3A%2F%2Fumbrellacost.io&response_type=code&kc_idp_hint=okta-oidc
   • Controlled access: Skip group assignment for now

Optional, to add users and roles from the IdP, follow the steps below

1. Navigate to Directory > Profile editor page and click on the application you created in step #2.
2. Click on Add Attribute and enter the following information:
   • Variable Data Type: string array
   • Display name: external Role Ids
   • Variable name: externalRoleIds
   • Enable the “Define enumerated list of values” check box
   • Under the attribute members value enter the role IDs you received from Umbrella
   • Enable the Attribute required checkbox
   • For Attribute type choose the group option
3. Click on Save Attribute

Save the app and send the information to Umbrella

1. Navigate to the Applications page and choose the application you created in step #2.
2. Copy the following values and forward them to Umbrella support to complete the configuration on Umbrella's side ([email protected]):
   1. Client ID (go to General > Client Credentials > Client ID)
   2. Client secret (go to General > Client Credentials > Client secret)
   3. The issuer (go to Sign On > OpenID Connect ID Token > Issuer)
   4. A list of all email domains.
3. Under the Assignments tab, you can invite users to the Umbrella platform
   1. If you have defined role mapping - Choose which roles should be assigned per user.

OKTA Using SAML

1. Access OKTA admin Console.
2. Navigate to Applications > Applications page, and click on Create App Integration.
3. Choose SAML 2.0 and click on Next.
4. In the SAML setting enter the following:
   • Single sign-on URL: https://login.umbrellacost.io/auth/realms/REALM_ID/broker/okta-saml/endpoint
   • Audience URI (SP Entity ID): https://login.umbrellacost.io/auth/realms/REALM_ID
   • Name ID format: EmailAddress
   • Application username: Email
5. Under the section of Attribute Statement write the following:
   • Name:email - Value: user.email
   • name: firstName. - Value user.firstName
   • name: lastName - Value user.lastName
6. Navigate to the Sign On tab and copy the Metadata URL - save and send it to Umbrella support to complete the configuration on Umbrella's side ([email protected]).
7. Click on Next, and Finish.

Optionally, to add users and roles from the IdP, follow the steps below

1. Navigate to Directory > Profile editor page and click on the Application you just created.
2. Click on Add Attribute and enter the following information:
   • Data type - string array (to support multiple role mapping with Umbrella)
   • Display name: Umbrella Role Ids
     • This is the Display name, use a meaningful name for you, it has no impact on the integration with Umbrella
   • Variable name: external_role_ids
   • Enable the “Define enumerated list of values”
   • Under the attribute members value enter the role IDs you received from Umbrella
   • Enable the Attribute required checkbox
   • For Attribute type choose the group option ("Personal" is also possible, but then it forces assignment by user and repeat the process for each user this is required for).
3. Click on Save Attribute.
4. Navigate to the Applications > Applications page and click on the application you created.
5. Under the general tab, click on Edit SAML Settings.
6. Under the Attribute Statement write the following:
   • Name: externalRoleIds
   • Value: appuser.external_role_ids
7. Navigate to the Sign On tab and copy the Metadata URL - save and send it to Umbrella support to complete the configuration on Umbrella's side ([email protected]).
8. Under the Assignments tab, you can invite users to Umbrella platform.
   1. If role mapping was configured, choose which roles should be assigned per user.

Response from Umbrella

1. Upon reception of your metadata file, Umbrella will generate a signature certificate file, this file will be sent to you by Umbrella CS.
2. Import that file to the Okta application's certificate Signature field.
   1. Okta > applications > the application created in previous steps > General > SAML settings > edit > "Next" > Show advanced settings > Signature certificate > "browse files"
3. Once the file is uploaded, you can set the "Enable single logout" checkbox.
   1. This means that logging out in Umbrella will logout in Okta app, which will require re-login to Okta app to re-login to umbrella.
   2. Single logout URL: https://login.umbrellacost.io/auth/realms/REALM_ID/broker/okta-saml/endpoint
   3. SP Issuer: https://login.umbrellacost.io/auth/realms/REALM_ID