Cumulocity IoT SSO Integration with Okta

[jhoo (Josh Hooks)]

Cumulocity IoT can integrate with Okta as an identity provider (IDP) using OpenID Connect. The connection can be made with out of the box functionality from both Cumulocity IoT and Okta. This document will guide users through the process of making the initial integration.

Prerequisites

1. Cumulocity IoT tenant with access to the Administration application and permissions to modify Authentication settings
2. Okta account with permissions to create custom applications and custom authorization servers

Okta Setup

1. Log into the Okta console and navigate to the Applications page
   

2. Click “Create App Integration” and choose a Sign-in method of “OIDC-OpenID Connect” and Application type of “Web Application”
   

3. Fill out the form using the following guidelines:
   a. App integration name: This can be whatever you want it to be, since it is only referenced in the Okta console
   b. Grant type: The only boxes checked here should be “Authorization Code” and “Refresh Token”
   c. Sign-in redirect URIs: Provide the URL that your Cumulocity IoT tenant uses for redirects, which is in the format of /tenant/oauth (e.g., https://tenant123.us.cumulocity.com/tenant/oauth)
   Note: You can also find the Redirect URI in the Cumulocity IoT tenant’s Single sign-on configuration page
   d. Controlled Access: Click on the appropriate permissions you wish to give for other Okta users to access this application

4. Save the newly created application

5. Within the new application:
   a. Navigate to the “General” menu and make note of the “Client ID” and “Client Secret”
   

   
   
   b. Navigate to the “Assignments” menu and add any users that you want to be able to log in to Cumulocity IoT using Okta SSO

6. Navigate to “Security → API”
   

7. Click the edit button next to the default authorization server
   a. Note: Remember the “Audience” value here because you’ll need it later for the Cumulocity IoT setup

8. Within the default authorization server, navigate to the “Claims” menu
   

9. Use the “Add Claim” to add any of the user information needed from the screenshot above, which will be included in the JSON Web Token (JWT) that is returned to Cumulocity IoT
   Example:`
   
   Note: For more user info options to include in these claims, refer to the Okta Expression Language overview documentation

10. Save your new claims and, still within the authorization server, navigate back to the “Settings” menu and click on the “Metadata URI” link
    

11. An Okta metadata JSON document will display on the screen, which you should save for later use during the Cumulocity IoT setup

Cumulocity IoT Setup

1. Log into your Cumulocity IoT tenant with an admin account, and Navigate to the “Administration” application, and then the “Settings → Authentication → Single sign-on” screen and choose a template of “Custom”
   

2. Scroll down to the “Basic” section and enter the following values in the form
   a. Redirect URI: Leave as default value
   b. Client ID: Okta application client ID mentioned in step 5a of the Okta setup
   c. Button name: The text you want to see on the login screen button (Example: “Login with Okta SSO”)
   d. Token issuer: The “issuer” URL listen in the Okta metadata JSON document
   e. Audience: Value for audience mentioned in step 8 of the Okta setup
   f. Provider Name: Use “Okta”
   g. Visible on Login Page: Check this option

   Example:
   

   

3. Scroll up to the “Authorization request” form and enter the following values into the form
   a. URL: The “authorization_endpoint” URL from the Okta metadata JSON document
   b. Headers: N/A
   c. Request Parameters: Add request parameters for the following variables
   response_type: code
   redirect_uri: ${redirectUri}
   state: state-296bc9a0-a2a2-4a57-be1a-d0e2fd9bb601
   client_id: ${clientId}
   scope: openid

   Example:
   

4. Scroll down to the “Token request” form and enter the following values into the form
   a. URL: The “token_endpoint” URL from the Okta metadata JSON document
   b. Body: grant_type=authorization_code&code=${code}&client_id=${clientId}&client_secret=<your_client_secret_here>&redirect_uri=${redirectUri}&scope=openid
   Note: Remember to replace the placeholder for client secret and scope in the body value
   c. Headers: N/A
   d. Request Parameters: N/A

   Example:
   

5. Scroll down to the “Refresh request” form and enter the following values into the form
   a. URL: The “token_endpoint” URL from the Okta metadata JSON document
   b. Body: grant_type=authorization_code&code=${code}&client_id=${clientId}&client_secret=<your_client_secret_here>&redirect_uri=${redirectUri}&scope=openid
   Note: Remember to replace the placeholder for client secret in the body value
   c. Headers: N/A
   d. Request Parameters: Add request parameters for the following variables
   response_type: refresh
   client_id: ${clientId}

   Example:
   

6. Scroll down to the “Logout request” form and enter the following values into the form
   a. URL: The “end_session_endpoint” URL from the Okta metadata JSON document combined with “?redirect_uri=${redirectUri}” (Example: https://dev-941791.okta.com/oauth2/aus2i41opp6UqtQb8357/v1/logout?redirect_uri=${redirectUri})
   b. Request Parameters: Add request parameters for the following variables
   client_id: ${clientId}

   Example:
   

7. Scroll down to the “Access mapping” form and use it to assign values within the JWT returned to Cumulocity IoT to roles within the tenant, which is documented here

   Example (Full Admin Access):
   

8. Scroll down to the “User ID” form and uncheck “Use constant value”, and enter in the “JWT field” which JWT key you would like to use to match to the Cumulocity IoT username
   Note: “sub” works well as a value in this example, but you can play around with other keys by logging in with the SSO user and checking the audit logs, which shoes the full JWT

   Example:
   

   

9. (Optional) Scroll down to the “User data mappings” form and enter the values into the form based on the claims you entered during the Okta SSO setup. These will automatically populate in the Cumulocity IoT’s user profile.

   Example:
   

   

10. Scroll down to the “Signature verification” form and enter the following values into the form
    a. Verifier: JWKS
    b. JWKS URI: The “jwks_uri” URL from the Okta metadata JSON document

    Example:
    

Final Steps

SSO logins should now work for any user setup in the Okta application’s assignment screen (Okta setup step 5b). Your login page should look like the screenshot below, and clicking on the “Login with Okta SSO” button should redirect you to Okta’s authentication screen.

This guide does not cover the many options available in Okta to control authorization with their IDP. For more options, reference the Okta developer guide.

[siegfried.wiebe]

We are trying to integrate Cumulocity IoT SSO Integration with SAP CDC as IDP using OpenID Connect.
I did the Cumulocity IoT Setup according to this article. However, when trying to login with SSO, we get the following error:
{“error”:“Authorization or authentication failed/Unauthorized”,“message”:“Cannot decode token from authorization server. Check JWT token format and Base64 encoding. : typ is not "JWT"”}

When I call the configured authorize-/token endpoints on CDC side with postman everything seems to be fine. The token response contains a json object with access_token (jwt), id_token (jwt) and refresh_token.

Any idea, what causes the error?