Okta

Configure Okta as the Single Sign-On provider for your organization on the Akuity Platform.

There are two ways to connect Okta. Pick one:

Method	Connector type	Credential	Group mapping
Okta OIDC	Okta	Client ID and secret	Not supported
Okta with SAML	SAML	Metadata XML	Supported

Okta's native integration does not support the groups claim, so if you need to map Okta groups to Akuity roles or teams you must use the SAML method.

info

Akuity Platform SSO is available on Enterprise plans only. Please contact our Sales Team to access the feature.

The owner role on the Organization is required to configure SSO.

Okta OIDC

Connect Okta through its native connector. This is the quicker setup, but it cannot map groups.

caution

Okta native integration does not support groups claim, please use generic SAML/OIDC instead if you want to use IDP groups mapping features.

1. Go to Organization > SSO.

   

2. Click Add Configuration.

3. Create an Okta OIDC Application.

   • In your Okta Admin Dashboard, Select Applications > Applications, and Create App Integration.
   • Select Create New App.
   • Choose OIDC as the Sign-in method and Web Application as Application Type.
   • Set Sign-in redirect URIs with https://auth.akuity.io/login/callback and select Create.
   • Copy your Client ID and Client Secret.
   • (Optional) You can configure Initiate login URI to skip Akuity login page.
     • Set Login initiated by under General Settings as Either Okta or App
     • Set Login flow as OIDC Compliant
     • Set Initiate login URI as https://akuity.cloud/api/auth/login/sso/<your-organization-id> (ID can be found in Organization tab in Akuity Dashboard)

4. Populate the configuration details on the form.

   • Client ID: Okta OIDC Application Client ID
   • Client Secret: Okta OIDC Application Client Secret
   • Okta Domain: Your Okta domain.
   • Domain Aliases: Additional domains to match organization members (e.g. some-org.com).
   • Auto Add Member: Allow your organization members to join your organization with the member role automatically.

note

For security purposes, your domain and domain aliases will be submitted to Akuity for manual review and approval.

Okta with SAML

Connect Okta over SAML 2.0. Use this method if you need IDP groups mapping.

1. Go to Organization > SSO.

   

2. Click Add Configuration.

3. In your Okta Admin Dashboard, go to Applications → Applications → Create App Integration.

   

4. Select SAML 2.0 as the sign-in method, and click Next.

   

5. Provide the app name and logo, then click Next.

   

6. In the Configure SAML section, set the following:

   • Single Sign-On URL: https://auth.akuity.io/login/callback?connection=<your_organization_id>

   • Audience URI (SP Entity ID): urn:auth0:akuity:<your_organization_id>

   In the Attributes Statements section, add:

   Name	Name format	Value
   email	Unspecified	user.email
   given_name	Unspecified	user.firstName
   family_name	Unspecified	user.lastName

   In the Group Attribute Statements section, add the following. You can modify the group regex according to your needs.

   Name	Name format	Filter
   groups	Unspecified	Matches regex : .*

   

7. Click Next, then Finish.

   

8. Go to the application details page, select the Sign On tab, then find and click View SAML setup instructions on the right side.

   

9. This opens a How to Configure SAML 2.0 for <app-name> Application page, where you can find the XML IdP metadata. Copy the XML.

   

10. Return to the Akuity Platform and select SAML from the Type dropdown.

11. Choose XML as the configuration type and paste the metadata you copied into the Metadata XML input.

    

12. Add your SSO email domain in the Domain input field.

13. Click the Enforce SSO toggle if you want to enforce SSO login for your organization members. If this is disabled, users will have the option to log in with SSO or with social login like Google.

Important

Enforcing SSO will require all organization users to use SSO for login. If your SSO configuration is broken, you may be locked out from your account and require contact with support.

Make sure to thoroughly test your SSO configuration before enforcing it for all users.

14. Optionally, enable the IdP Initiated SSO toggle if you want users to be able to log in directly from Okta without first visiting the Akuity Platform.

Security Risk: IdP-Initiated SSO

Auth0, the identity provider powering Akuity Platform authentication, does not recommend enabling IdP-Initiated SSO.

In an IdP-Initiated flow, Auth0 receives an unsolicited response from the IdP and the application receives an unsolicited response from Auth0. Neither entity can verify that the user actually started the flow. This opens the possibility of a Login CSRF attack, where an attacker can trick a legitimate user into unknowingly logging into the application with the identity of the attacker.

Whenever possible, keep this disabled and let authentication be initiated from the Akuity Platform (the default). Only enable this if your IdP requires initiating the login flow and you understand the risks involved.

15. Create the configuration by clicking Add.

16. Now, if you try to log in with an email associated with the domain you just configured, you will be redirected to Okta.

Next: map Okta groups to roles and teams

With the groups claim flowing, you can map Okta groups to Akuity roles and teams. See IDP Groups Mapping and OIDC Team Mapping at the bottom of this page.

IDP Groups Mapping

caution

IDP Groups does not work for Okta native integration as Okta does not support groups claim. Please use generic SAML/OIDC option instead to connect with Okta if you want to use this feature.

To configure IDP Groups for an Organization in the Akuity Platform:

1. Go to Organization > SSO.

   

2. Click Add New Rule.

   

3. In the Add OIDC Group Mapping select the role and specify the corresponding OIDC Group for your provider.

   

4. Click the Add button.

note

In the SSO settings, if the Auto Add Member is checked the new user will join your organization with the member role automatically.

OIDC Team Mapping

caution

OIDC Team Mapping does not work for Okta native integration as Okta does not support groups claim. Please use generic SAML/OIDC option instead to connect with Okta if you want to use this feature.

This feature allows you to map users with a specific OIDC group to a team in your organization.

Your organization must have at least one Team.

To configure this feature for an Organization in the Akuity Platform:

1. Go to Organization > SSO.

   

2. Scroll down to the "OIDC Team Mapping" section and click Add New Mapping.

   

3. In the modal that appears, specify an OIDC group and select an existing team from the dropdown.

   

4. Click the Add button.

Now, when a user logs in with the specified IDP group, they will be added to the selected team in your organization.