⚒️Configuring SSO with Okta
Last updated
Last updated
Create a new Okta developer account (Okta Developer) and a tenant for your organization.
This application will represent the Cubu web application to Okta and your users. It manages the login experience and is the gateway used to obtain the access tokens to the Cubu API.
Go to Applications > Applications in the Okta admin portal and click the Create App Integration button.
In the Create a new app integration dialog, select the OIDC - OpenID Connect sign-in method and the Single-Page Application application type.
Give your application an easy to recognize name. This guide will use cubu-client as the name in future references.
Make sure that the Authorization Code Grant type is checked and all of the other grant types are unchecked.
In the Sign-in redirect URIs, fill in: https://YOUR_ORG_SUBDOMAIN.app.cubu.com
In the Sign-out redirect URIs, fill in: https://YOUR_ORG_SUBDOMAIN.app.cubu.com/logout
In the Trusted Origins section’s Base URIs, fill in: https://YOUR_ORG_SUBDOMAIN.app.cubu.com
In the Controlled Access section, select which users in your Okta directory can access Cubu.
After saving the new application, write down the Client ID since it will be used later to configure SSO for your organization in Cubu.
This Server will issue tokens used to access the cubu API.
(Alternatively, you can use the default authorization server if it suits your needs. Just make sure to adjust the relevant settings).
Write down the API’s audience as it will be used later when configuring SSO in your cubu organization.
Add required claims to the access token. Cubu relies on having the user’s email claim in the access token for user creation. The given_name, family_name, and picture claims can be added to the identity token in the same manner to automatically add it to new users for personalization (users can change those values later in cubu).
In the Add Claim dialog set the following values:
Name: email (lowercase)
Include in token type: Access Token
Value type: Expression
Value: user.email
Disable claim: unchecked
If you created a new authorization server rather than using the default one, the cubu-client app needs to be allowed to issue access tokens using the cubu-api authorization server.
Click the Enable SSO button and enter your auth provider’s information in the Enable SSO dialog in the following way:
Identity service provider (ISP): Okta
Authority: The cubu-api authorization server’s Issuer URI preceded by https:// (e.g., https://dev-12346546.okta.com/oauth2/aus5a4sd56a4654)
Audience: The cubu-api authorization server’s audience (i.e., https://api.cubu.com)
Client ID: The cubu-client application’s client ID.
Organization owner email: The email of the organization user in your Okta tenant that will be associated with the current application owner user’s Cubu account.
After clicking Enable SSO in the dialog, the page should refresh, prompting you to log in.
Go to Security > API in the Okta admin portal and click the Add Authorization Server button.
In the Add Authorization Server dialog, give the API an easy-to-recognize name and an audience, which will be used when access tokens are issued.
We recommend using: "https://api.cubu.com" for the audience.
This guide will use cubu-api as the name in future references.
Switch to the Claims tab on the newly created authorization server’s page and click the Add Claim button.
Include in: Any scope
To do that, switch to the Access Policies tab of your authorization server and click Add Policy.
In the Add policy dialog, give the policy a name and description, select The following clients, and add the cubu-client app (you can select All clients if this tenant is dedicated to Cubu.
After the policy has been created, add a default rule and configure it to allow connections using (at least) the Authorization Code grant type with the desired users and (at least) the openid, profile, and email scopes.
Return to the authorization server list and copy the server’s Issuer URI. It will be used later to configure SSO in your Cubu organization.
Log in to your organization in Cubu with the user that created the organization in Cubu (organization owner) and navigate to the SSO page of the Settings tool in the Admin tools toolbelt.
