Replacing FIDO login in the Admin Console

If you have an existing IAM system for your administrative users, you can choose to have that system control login and access to resources in Digipass S3's Admin Console. To accomplish this, your IAM server creates a login JWT that identifies the admin user who is signing in, which tenant they can use during the current session, and their access to resources in the Admin Console. JWT is an open standard RFC 7519 method that compactly stores the payload in JSON format. Next, the IAM server redirects the request to Digipass S3's Admin Console with a cookie that contains the created JWT.

This section describes the claims and expected values for the login JWT, requirements for the cookie, the issuer configuration needed for your IAM server, and how to enable this feature in Digipass S3 Authentication Software.

For general background about the JWT format used by Digipass S3 Software, see JWT Format.

The login JWT claim set is a JSON object whose fields are the claims asserted by your IAM system. For example:

{
  "sub": "JSmith",
  "aud": "<audience>",
  "nbf": 1652897350,
  "tid": "EU",
  "scope": "adaptiveRulesets.write config.write userMgmt.read adminUserMgmt.write anyTenant",
  "iss": "https://example.com:8443",
  "exp": 1652900950,
  "iat": 1652897350
}

The claim set for the login token is different from that used by the JWT session token. The login token has 2 Digipass S3-specific claims: tid and scope.

Claim Name	Description
sub	Mandatory. String. Subject, in other words, the user name of the Admin user.
aud	Mandatory. String. Audience or the intended recipient. Must match the audiences field for the IAM server's configuration under validate.issuers. You can find this field in the Admin tenant's jwt_config object. See section Validate Fields in JWT Session Token.
nbf	Optional. Integer. Not before time. The time before which the JWT must not be accepted for processing. Present only if the jwt_config's generate.nbf_delta field is used.
tid	Optional. The tenant ID that the Admin user is allowed to access in the current login session. Omit if the user has the anyTenant permission
scope	Optional. Specifies the permission that the Admin user has to the associated scope resource. See Assigning User Permissions to scope.
iss	Mandatory. String. Issuer of the JWT. The URL of the IAM server.
exp	Mandatory. Integer. Expiration time. Time after which the JWT expires.
iat	Optional. Integer. Issued at time. The issuing date/time (number of seconds from epoch).

Assigning user permissions to scope

Based on the scope resources and permissions that you assign to the scope claim, you can specify one of the following 4 user types:

Super Admin: Can switch between tenants and has read/write access to specified resources.
Super Admin Read only: Can switch between tenants and has read access to specified resources.
Admin: Can access a single tenant and has read/write access to specified resources.
Admin Read Only: Can access a single tenant and has read access to specified resources.

Use the following syntax to assign a permission to a scope resource:

The anyTenant scope resource is an exception because its presence implies permission. Use a space to delimit multiple entries. If you don't want the Admin user to have access to a scope resource, don't list that resource in the scope claim.

Scope resource

You can use the following scope resources in the scope field. See Resource for the list of Admin Console pages tied to the resource.

Scope Resource	Resource
adaptiveRulesets	Rulesets
authMetadataMgmt	Metadata Management
config	Configuration
tenantMgmt	Create or delete tenants. Corresponds to the page accessed via Administration > Tenants.
userMgmt	End User Management
anyTenant	Listing this scope resource means that an Admin user can switch from one tenant to another.

Permission

A permission is the level of access that an administrative user has to a resource. One of:

read
write (includes delete, create, update, and read)

If anyTenant is in the JWT's scope claim, then the Admin user can switch tenants. You do not assign a permission to anyTenant.

Examples

Admin user with write access to all tenants

{
  "sub": "<user-id>",
  "aud": "<audience>",
  "nbf": 1652897350,
  "scope": "adaptiveRulesets.write config.write userMgmt.write adminUserMgmt.write authMetadataMgmt.write anyTenant",
  "iss": "<issuer>",
  "exp": 1652900950,
  "iat": 1652897350
}

Admin user with read-only access to all tenants

{
  "sub": "<user-id>",
  "aud": "<audience>",
  "nbf": 1652897350,
  "scope": "adaptiveRulesets.read config.read userMgmt.read adminUserMgmt.read authMetadataMgmt.read anyTenant",
  "iss": "<issuer>",
  "exp": 1652900950,
  "iat": 1652897350
}

Admin user with write access to a tenant with ID Marketing

{
  "sub": "<user-id>",
  "aud": "<audience>",
  "nbf": 1652897350,
  "tid": "Marketing",
  "scope": "adaptiveRulesets.write config.write userMgmt.write adminUserMgmt.write authMetadataMgmt.write",
  "iss": "<issuer>",
  "exp": 1652900950,
  "iat": 1652897350
}

Admin user with read-only access to a tenant with ID EU

{
  "sub": "<user-id>",
  "aud": "<audience>",
  "nbf": 1652897350,
  "tid": "EU",
  "scope": "adaptiveRulesets.read config.read userMgmt.read adminUserMgmt.read authMetadataMgmt.read",
  "iss": "<issuer>",
  "exp": 1652900950,
  "iat": 1652897350
}

Digipass S3 Software uses cookies that have a name of "AdminSessionKey" and a context of "/". Drop the login JWT into a cookie of this type.

Configuring your IAM server as an issuer

The API Server only accepts JWTs from known issuers. Add your IAM server as an issuer to the JWT Processor's configuration object called jwt_config. jwt_config specifies what servers can issue JWTs to the API Server as well as the information needed to verify and decrypt those JWTs.

Navigate to Configuration > API Server > Authentication API > Session Plugins > JWT Processor to view the current jwt_config or upload a modified one.

Below is a partial jwt_config object that contains an example issuer object for an IAM server in the validate.issuers array. The JWT sent from this IAM server is signed with the asymmetric ES256 algorithm whose public key is stored in a JWK set located at the endpoints specified by the jwks_uri field.

{
  "generate":{<list of fields and values>},
  "validate":{
    "issuers":[
      {
        "issuer":"<your IAMServer's URL>",
        "audiences":[
          "<your audience>"
        ],
        "max_clock_skew":180,
        "algorithm":"ES256",
        "jwks_uri":"<URL to your JWK set endpoint>"
      }
    ]
  }
}

Ensure that your issuer object specifies the same algorithm, the URI for your JWK set from where the public key can be fetched, and the audience used by your IAM server to create a login JWT. Make these changes to the Admin tenant's jwt_config.

For details about configuring jwt_config, see Configuring JWT Generation and Validation.
For instructions on how to export and import jwt_config in order to modify it, see Exporting a JWT Configuration Object and Importing a JWT Configuration Object.
For instructions on how to add an issuer to jwt_config, see Adding an Additional Issuer.

Use these instructions to configure the Admin Console to use a login JWT token sent by your IAM server to sign in an Admin User. When configuration is complete, the Admin Console disables the currently supported FIDO-based login mechanism.

Step 1. Using nnl-mgmt.sh, set the nnl.external.login.enabled Admin tenant property to true, as shown below. By default, this property is false.

./nnl-mgmt.sh properties set -name nnl.external.login.enabled -value true -tenantid Admin

This disables the following pages in the Admin Console:

registration
login
Admin User Management (Administration > Admin Users)
FIDO Authenticators (Settings > Authenticators)

Step 2. Assign the URL to your custom login page to the login.url property. This property is located in file <tomcat-home>/webapps/nnladmin/WEB-INF/classes/jwt-session-manager.properties.

tenant.id=Admin
root.tenant=Admin
login.url=https://sample.auth.com/login

Restart the server so the changes take effect.

Step 3. If you have a custom logout page, you can optionally assign its URL to the Admin tenant property nnl.logout.url. The application behind the logout URL should manage session invalidation. This logout URL is assigned to Settings > Log Out in the Admin Console.

./nnl-mgmt.sh properties set -name nnl.logout.url -value https://<your-domain>/AdminLogout.html -tenantid Admin