Understanding Cross Identity Authorization APIs

Cross Identity Authorization APIs provide a programmable interface to authorize users to access various resources in an application. If you wish to protect the resources in the application and grant access to these resources to corresponding users, you can use the CI’s Authorization APIs. These APIs are implemented based on OAuth and OpenID Connect Protocol. The OAuth 2.0 protocol provides API security via scoped access tokens, and OpenID Connect provides user authentication and Single Sign-On (SSO) functionality.

CI supports four different grant types:

1. Authorization Code
2. Implicit grant type
3. Resource Owner Password
4. Client Credentials

Based on the application design, you can choose which OAuth/OIDC flow & grant type you need to select for authorization. 

Authorization Code flow

At a high level, this flow has the following steps:

1. Your application (app) directs the browser to the Cross Identity's End-User sign-in page. Before implementing this redirect request to the Cross Identity Authentication, you need to onboard your app in CI as an OAuth application or OIDC Application to obtain a client ID to embed in your request. See API for requesting an authorization code.
2. CI redirects the authentication prompt to the user and authenticates the user. For CI to authenticate the user credentials, the user identity data should be in CI. Refer to Add Users, Import Users from Identity Sources, and import users using CSV in the documentation portal to on-abord users into CI’s Universal Identity Directory:
   • https://docs.crossidentity.com/docs/5-manage-identities
   • https://docs.crossidentity.com/docs/91-identity-sources-3
   • https://docs.crossidentity.com/docs/46-import-from-csv
3. CI sends the Authorization code to the app. After the user is authenticated, the browser receives an authorization code from Cross Identity. The authorization code is passed to your app.
4. The app sends this code and the client's secret to CI. See Exchange the code for tokens.
5.  CI returns access and ID tokens, and optionally a refresh token. Your app can now use these tokens to call the resource server (for example an API) on behalf of the user. The resource server validates the token before responding to the request. 

API to request an authorization code

GET <tenant_URL>/oauth2

This is a starting point for browser-based OAuth/OIDC flows such as the implicit and authorization code flows. This request authenticates the user and returns tokens along with an authorization grant to the client application as a part of the callback response.

Request Syntax:

Request Parameters:

The following parameters can be passed as a part of the URL-encoded form values to the API:

Request Syntax

API to request Token

POST {CI_Tenant_ULR}/oauth2token

This endpoint returns access tokens, ID tokens, and refresh tokens depending on the request parameters.

Request Syntax

Request Parameters

Request Syntax