How-tos

3 mins read

Integrating Third-party Applications for User Authentication

Connect third-party applications to ensure the correct and comprehensive authentication context resulting from user's authentication.

Feature flag

Post Authentication applications must be explicitly enabled in your tenant using the custom_apps feature flag. To enable the feature, contact Cloudentity Sales Team.

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

    Custom_app config

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

    Custom_app 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.

Abstract Flow

[mermaid-begin]
sequenceDiagram participant Client app participant Cloudentity participant IDP participant Custom app Client app->>Cloudentity: Request authorization code Cloudentity->>IDP: Request authorization code IDP-->>IDP: Authenticate user IDP-->>Custom app: redirect Custom app-->>Custom app: Run business process with the user Custom app-->>IDP: redirect IDP-->>Cloudentity: Issue authorization code Cloudentity->>IDP: Request ID tokens using the code IDP-->>Cloudentity: Issue tokens opt Cloudentity->>IDP: Pull user information IDP-->>Cloudentity: Return user data end opt Cloudentity-->>Cloudentity: Ask user for consent to share data with client app end Cloudentity-->>Client app: Issue authorization code Client app->>Cloudentity: Request tokens using the code Cloudentity-->>Client app: Issue tokens requested by the app

Add Post-AuthN Success Flow

  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.

Updated: Apr 14, 2023