Third-party Applications in a Nutshell

Cloudentity offers two options for extending the user authentication process: Post Authentication scripts and Post Authentication custom applications.

The Post Authentication script allows custom JavaScript code execution upon user’s authentication, enabling the modification of certain authentication context attributes, enhancement of the user context, or triggering custom API calls.

The Post Authentication custom application option described in this document allows connecting a Third-party Application to Cloudentity. This application can interrupt the authorization flow after the user logs in using an IDP, redirecting the user to a custom, business-specific application hosted by the customer. This application requires users to complete additional processes or interactions as needed during the authentication process before they can proceed to granting their consent to the client. When the user completes this third-party flow, they are redirected back to the original authorization flow.

Feature flag

Post Authentication applications must be explicitly enabled in your tenant using the custom_apps feature flag.

These custom business processes might include:

• Asking the user to provide missing profile attributes

• Asking the user to provide additional context for the authentication process, like State, District or Organization

• Triggering a separate custom business process that requires user interaction

Examine the OAuth authorization flow with the third party app:

Register Application in Cloudentity

1. Go to Extensions > Custom Apps.

2. Click + Custom Application.

3. Fill in the application data.

   Field	Description
   Type	Application type
   Name	Name to identify this application
   Application URL	Your third-party application URL that Cloudentity will redirect the user to during the
   authentication process

4. Click Create.

   Your application is now added to Cloudentity as a client in the system workspace. It generates a Client ID and Client Secret so that your application can authenticate with Cloudentity to perform various operations.

   Example Third-party Application registration

   

Associate Application to IDP

1. Go to Identity Providers > YOUR_IDP > Extensions.

2. In the Post Authentication application field, select your application. Once selected, users will be redirected to the application after login.

   Example Third-party Application association

   

Post-Authn Success Flow

Use case: After authentication, the Post-Authn Third-party Application prompts the user for additional information and that information is added to the user’s authentication context.

1. Cloudentity Authenticates the user

2. Cloudentity redirects to the Application URL specified in your Custom App configuration and adds a query string with login_id and login_state.

   https://myapplication.com?login_id=REDACTED&login_state=REDACTED

   1. The Third-party Application receives the redirect with the query string.

   2. Authenticate to Cloudentity using client_secret_basic method with the generated credentials from registering the Third-party Application (Client ID, Client Secret) POST Authn-client-secret-basic.

   3. Retrieve the user’s current session GET post-authn-session.

   4. Retrieve additional information from Third-Party datastore.

   5. Display options to user.

   6. User selects an option and clicks Submit.

   7. Construct the Authn Complete JSON and put the user selected values into the authentication_context

      {
        "authentication_context":{     # User's authentication context
          "organizationId":"6502",     # Additional attributes
          "organizationName":"Acme Inc.",
          "permissions":[
            "acme:ViewDashboard",
            "acme:CreateOrder",
            "acme:ViewOrder"
          ]
        },
        "id":"REDACTED",            # Required login_id
        "login_state":"REDACTED"    # Required login_state
      }
      

   8. Send post-auth Complete with the authentication_context POST post-authn-complete.

   9. Receive Cloudentity response containing redirect.

      {
        "redirect_to":"https://my-tenant.us.authz.cloudentity.io/my-tenant/my-workspace/oauth2/authorize?..."
      }
      

   10. Execute the redirect_to contained in the Cloudentity response.

3. Cloudentity proceeds to the next step in the Authentication process.

Post-Authn Abort Flow

Use case: After authentication, the Post-Authn Third-party Application process failed.

1. Cloudentity authenticates the user.

2. Cloudentity redirects to the Application URL specified in your Custom App configuration and adds a query string with login_id and login_state: https://myapplication.com?login_id=qwerty&login_state=asdfg

   1. The Third-party Application receives the redirect with the query string.

   2. Authenticate to Cloudentity using client_secret_basic method with the generated credentials from registering the Third-party Application (Client ID, Client Secret) POST Authn-client-secret-basic.

   3. Retrieve the user’s current session via GET post-authn-session.

   4. Retrieve additional information from Third-Party datastore.

   5. An error occurs or the user lacks permission, organization, etc.

   6. Construct the abort JSON.

      {
        "status":403,
        "error":"AccessDenied",
        "error_description":"User denied access",
        "id":"REDACTED",
        "login_state":"REDACTED"
      }
      

   7. Send post-auth Abort with the abort JSON via POST post-authn-abort.

   8. Receive Cloudentity response containing redirect

      {
        "redirect_to":"https://my-tenant.us.authz.cloudentity.io/my-tenant/my-workspace/oauth2/authorize?..."
      }
      

   9. If the Cloudentity error page is desired, execute the redirect_to contained in the Cloudentity response.

   10. Else, display third-party error page. The Third-party Application does not return to Cloudentity in this case.

3. If redirected back to Cloudentity, Cloudentity displays a generic authentication failure message.