Okta uses OAuth protocol to issue tokens that control access to web APIs. To request these tokens, you must first register your application with an Okta authorization server. Follow the steps below to set up an Okta authorization server:
Create an Okta account
To get started, sign up for an Okta account or sign in using an administrator account.
Create a new user
-
In the Okta Admin Console, go to Directory > People.
-
Select Add Person to manually add users or import them from a directory.
-
Assign the user to an existing group. If necessary, create a new group.
Assign users to a group
-
In the Okta Admin Console, go to Directory > Groups.
To create a new group, select Add Group and enter the details.
-
Select the group > Manage People and then choose the users.
-
Select Save.
Create an application
Okta refers to clients as applications.
-
In the Okta Admin Console, go to Applications > Applications.
-
Select Create App Integration.
-
Select OIDC - OpenID Connect as the Sign-in method.
-
For Application type, select Single-Page Application, and then select Next.
-
Enter the details as follows:
Setting
Description
App integration name
Name of the client application. Enter the name in this format: estateshortcode-appid-sitename-authflow
Example: siv3-si-app-pkce
The application name must consist of UTF-8 encoded characters.
Grant type
Okta authorizes your application requests with these OAuth grant types. Select Authorization Code (default) and Refresh Token.
Sign-in redirect URIs
URIs of the server where your application is hosted. Okta sends the authentication response and ID token for the sign-in request to these URIs.
Example:
http://localhost:8080/callback
https://sandbox.intergraphsmartcloud.com
Sign-out redirect URIs
After your application contacts Okta to close the user session, Okta redirects the user to one of these URIs.
Example:
http://localhost:8080/callback
https://sandbox.intergraphsmartcloud.com
Assignments
Specifies which users or groups can access the application. Select Limit access to selected groups and type the group name.
-
Select Save.
-
After saving, copy the Client ID and save it for future use. Also, ensure the Client authentication is set to PKCE.
Generate audience GUID for authorization server
The audience GUID is required when you create a custom authorization server. The audience represents the intended recipient of tokens issued by the server and is included in the aud claim of OAuth 2.0 and OpenID Connect tokens. This ensures that tokens are only accepted by the correct resource or API.
Okta requires the Audience value to be a Globally Unique Identifier (GUID) in uppercase
format. This GUID acts as a secure identifier for your resource server.
-
Generate a GUID. For example, go to https://www.guidgenerator.com and generate a GUID.
You can use online GUID or UUID generators, command-line tools, or any programming
languages to generate the GUID.
-
Ensure the GUID is in uppercase. Convert it if necessary. For example:
Lowercase: 123e4567-e89b-12d3-a456-426614174000
Uppercase: 123E4567-E89B-12D3-A456-426614174000
-
Save the GUID to use it later when adding the authorization server.
Add an authorization server
-
In the Okta Admin Console, go to Security > API.
-
On the Authorization Servers tab, select Add Authorization Server and enter the details.
-
In the Audience box, paste the GUID you generated, and then select Save.
-
In the Settings tab, change the Issuer to Custom URL and enter the authorization server URL in the format - https://[yourOktaDomain]/oauth2/[authorizationServerId]. For example, https://sandbox.intergraphsmartcloud.com/oauth2/aus3u65bQjox7
Create API access scopes
-
In the Okta Admin Console, go to Security > API and select the authorization server you created.
-
On the Authorization Server details page, select the Scopes tab and then select Add Scope.
-
Create the audience GUID scope as follows:
Setting
Value
Name
Enter the audience GUID that you generated.
Display phrase
Enter Smart API Service.
Description
Enter a description. For example, allows you to access resources from Smart APIs.
User Consent
Select Implicit.
Metadata
Select Include in public metadata.
-
Select Create.
-
Create the ingr.api scope as follows:
Setting
Value
Name
Type ingr.api
Display phrase
Enter a short description. For example, access resources.
Description
Enter a description. For example, allows you to access resources from Smart APIs.
User Consent
Select Implicit.
Metadata
Select Include in public metadata.
-
Select Create.
Create API access claims
-
On the Authorization Server details page, select the Claims tab, and then select Add Claim.
-
Create the ingr.session_id claim as follows:
Setting
Value
Name
Type ingr.session_id
Include in token type
Select Access Token.
Value type
Select Expression.
Value
Type Time.now("")
Include in
Select Any scope.
-
Select Create Claim.
-
Create another claim as follows:
Setting
Value
Name
Type a name.
Include in token type
Select Access Token.
Value type
Select Expression.
Value
Type String.join(" ", user.firstName, user.lastName)
Include in
Select Any scope.
-
Select Create Claim.
-
Locate the sub claim. It is usually listed as a system claim.
-
Modify the following values in the sub claim:
Setting
Value
Value type
Select Expression.
Value
Enter(appuser != null) ? (!Arrays.isEmpty(user.estateUsers)) ?
String.substringBefore("SEM"+String.substringBefore(String.substringAfter(Arrays.to CsvString(user.estateUsers)+",", "SEM"),","),"@") : String.substringBefore(user.login,"@") : ((app.profile.Username != null) ?
app.profile.Username: app.clientId)
Set up API access policies
-
On the Authorization Server details page, select the Access Policies tab, and then select Add Policy.
-
Create the policy as follows:
Setting
Value
Name
Enter a name. For example, Smart Instrumentation.
Description
Enter a description. For example, allows to share resources between the client and API.
Assign to
Select The following clients:, and then type the client application name that you created. For example, siv3-si-app-pkce.
-
Select Create Policy.
-
Select the policy you just created, and then select Add Rule.
-
Define which grant types can request tokens and set the token lifetime, as follows:
Setting
Value
Rule Name
Enter a name. For example, Smart Instrumentation.
IF Grant type is
Select Authorization Code.
AND User is
Select The following clients:, and then type the client application name that you created. For example, siv3-si-app-pkce
AND Scopes requested
Select Any scopes.
THEN Access token lifetime is
Set to 1 Days.
AND Refresh token lifetime is
Select Unlimited.
but will expire if not used every
7 Days
-
Select Create Rule.
Test the authorization server configuration
-
On the Authorization Server details page, select the Token Preview tab.
-
In the Request Properties section, enter the following details:
Setting
Value
Oauth/OIDC Client
Select the client you created. For example, siv3-si-app-pkce.
Grant type
Select Authorization Code.
User
Select the logged in user or the user assigned to this client.
Scopes
Enter the following scope names: [audience GUID], ingr.api, openid, profile
-
Select Preview Token to see the resulting tokens.