Skip to content

Index

Note

This information can be used by either STRATO node administrators or STRATO Application developers.

This page contains the step-by-step information on how to configure an Identity Provider to comply with the requirements of STRATO and applications built for it.

General Requirements

The list of required credentials to run STRATO node and STRATO Application (application using STRATO API):

  • STRATO Node:
    • OpenID Discovery URL (aka "well-known url")
    • Client ID
      • Client must be configured with redirect URL https://<strato_address>/auth/openidc/return
      • Client must have Authorization Code grant flow enabled
    • Client Secret
  • STRATO Application:
    • OpenID Discovery URL (aka "well-known url") matching the one used for STRATO node
    • Client ID
    • Client must be configured with redirect URL exposed by your Application, e.g. https://<my_app_url>/api/v1/authentication/callback
    • Client must have both Authorization Code grant and Client Credentials flow grants enabled. Note that some Identity Providers (e.g. AWS Cognito) do not let multiple grant flows on a single client. Create two separate clients in such case (see AWS Cognito Setup as a reference)
    • Client Secret

Below are the suggested steps to configure some of the popular Identity Providers.

AWS Cognito Setup

Follow these steps to setup AWS Cognito through the AWS Console:

  1. Create a user pool (use default settings unless you know what you are changing.)
  2. Under App Integration -> Domain Name select the Amazon Cognito domain prefix to use (e.g. myapp.)

  3. Create dummy resource server and custom scope (required for client-credentials flow):

    • Go to App Integration -> Resource server.
    • Click “Add a resource server”.
    • Provide fields:
      • Name: any string, (e.g. My app)
      • Identifier: any URL (e.g. http://myapp) (this is not used)
      • Scope name: any string (e.g. dummy)
      • Description: (required) any string (e.g. dummy scope for client-credentials flow)
    • Save changes.

  4. Create a new App Client under General Settings -> App Clients. The name will be set to myapp-localhost (use default settings unless you know what you are changing), Hit "Create app client".

  5. Get a secret key for this new client (hit "Show details" button). Note the client ID and the client secret.
  6. Go to App Integrations -> App Client Settings. Enable your user pool for the App Client created in step 3 (Check "Enabled Identity Providers -> Cognito User Pool".)
  7. Configure the Callback and Sign In URLs. For example, a localhost Callback URL can be set to http://localhost/api/v1/authentication/callback, and the Sign Out URL can be set to http://localhost (see OAuth2 Authorization Code Grant Flow Documentation for details.)
  8. Under the OAuth 2.0 section, enable "Authorization Code Grant Flow". Enable "Allowed OAuth Scopes": openid, email, profile; Click "Save changes".

At this point the OpenID Discovery URL https://cognito-idp.<amazon-region-id>.amazonaws.com/<user-pool-id>/.well-known/openid-configuration should be able to be queried. user-pool-id is found in General Settings ("Pool Id"); amazon-region-id is an Amazon region name shorthand, e.g. "us-east-1".

The OpenID Discovery endpoint should respond with data similar to the following (note the token_endpoint value with /oauth2/ in the URL):

{
  "authorization_endpoint": "https://myapp.auth.ap-south-1.amazoncognito.com/oauth2/authorize",
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "issuer": "https://cognito-idp.ap-south-1.amazonaws.com/ap-south-1_pIYXBtoXp",
  "jwks_uri": "https://cognito-idp.ap-south-1.amazonaws.com/ap-south-1_pIYXBtoXp/.well-known/jwks.json",
  "response_types_supported": [
    "code",
    "token"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "phone",
    "profile"
  ],
  "subject_types_supported": [
    "public"
  ],
  "token_endpoint": "https://myapp.auth.ap-south-1.amazoncognito.com/oauth2/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post"
  ],
  "userinfo_endpoint": "https://myapp.auth.ap-south-1.amazoncognito.com/oauth2/userInfo"
}

Note

If the token and authorization endpoints for your Identity Provider do not include /oauth2/ in the URL, your Cognito User Pool is not setup correctly.

The steps above created an App Client to run an application on a localhost.

Repeat the steps 4-8 from above with the listed changes to create App Clients for different scenarios:

  • A - Local App (Authorization Code Grant flow)

  • B. Local App for programmatic token fetch (Client Credential Grant flow)

    • in (4) use App client name = myapp-localhost-service.
    • in (8) enable Client Credential flow instead; Check "scope" under "Allowed custom scope" instead (created in step 3)

  • C. Remote STRATO node:

    • in (4) use App client name = strato-node1.
    • in (7) use Callback URL = https://<strato_address>/auth/openidc/return (note the "https" and port!), Sign In URL = https://<strato_address>/ (note the "https" and include the port of your STRATO deployment.)

  • D. Remote App:

    • in (4) use App client name = myapp-node1.
    • in (7) use Callback URL = https://<my_app_url>/api/v1/authentication/callback (note "https" and no port!), Sign In URL = https://<my_app_url>/ (note the https and include the port of your application deployment.)

  • E. Remote App for programmatic token fetch (Client Credential flow):

    • in (4) use App client name = myapp-node1-service.
    • in (7) use Callback URL = https://<my_app_url>/api/v1/authentication/callback (note "https" and no port!), Sign In URL = https://<my_app_url>/ (note the https and include the port of your application deployment.)
    • in (8) enable Client Credential flow instead; Check "scope" under "Allowed custom scope" instead (created in step 3.)

Provide the following information to the STRATO node's administrator, so they can setup the node (running on \) using the Cognito user pool:

  1. OpenID Discovery URL of the user pool.
  2. Client ID and secret for the App Client if you are using scenarios C, D or E.

Use AWS Cognito credentials in STRATO application (with blockapps-rest SDK)

This is an example config.yaml for using AWS Cognito with blockapps-rest SDK when developing for scenario A, Local App: 

<...>
nodes:
  - id: 0
    url: "https://<strato_address>"
    publicKey: "6d8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0"
    port: 30303
    oauth:
      appTokenCookieName: "myapp_session"
      appTokenCookieMaxAge: 7776000000
      openIdDiscoveryUrl: >-
        https://cognito-idp.<amazon-region-id>.amazonaws.com/<user-pool-id>/.well-known/openid-configuration
      scope: openid email profile
      clientId: <client id of AppClient myapp-localhost>
      clientSecret: <client secret of AppClient myapp-localhost>
      redirectUri: https://<application_host>/api/v1/authentication/callback
      logoutRedirectUri: https://<application_host>/
      # oauthUsername: username/email/sub #(check for what's in token payload, if needed)
      serviceFlow: client-credential     
      serviceFlowClientId: <client id of AppClient myapp-localhost-service>
      serviceFlowClientSecret: <client secret of AppClient myapp-localhost-service>
      # serviceFlowClientScope: openid email profile #(TBD if required)
<...>

Run STRATO on-premise with AWS Cognito

Use the following environment values when the entire node should be locally deployed: 

NODE_HOST=<strato_address>:8080 \
  HTTP_PORT=8080 \
  OAUTH_ENABLED=true \
  OAUTH_DISCOVERY_URL=https://cognito-idp.<amazon-region-id>.amazonaws.com/<user-pool-id>/.well-known/openid-configuration \
  OAUTH_CLIENT_ID=<client-id-for-strato-app-client> \
  OAUTH_CLIENT_SECRET=<client-secret-for-strato> \
  OAUTH_JWT_USERNAME_PROPERTY=sub \
  VAULT_URL=https://<vault_hostname>:<vault_port>  \
  ./strato --blockstanbul