3DS Admin OIDC support

Introduction

Starting from release 2.5.0.0, there are two modes of authenticating the 3DS Admin UI users:

  • Internal mode of authentication (the already present option) - the users will be managed by the 3DS Admin UI itself
  • External mode of authentication - the users are managed by an external OIDC provider (IAM provider)

The two options are mutually exclusive, i.e. the 3DS Admin UI can either run the authentication in internal or external mode.

The option for authenticating users against an external OIDC provider implies that the 3DS Admin UI now supports the OIDC protocol built on top of OAuth 2. Find more information on it in the official OIDC protocol documentation .

Configuration of the 3DS Admin UI authentication mode

The authentication mode of the 3DS Admin UI should be configured before its startup. For this purpose, a new configuration property was introduced:

The allowed values are internal or external. The default value is internal, i.e. if not configured differently, the users will be managed by the 3DS Admin UI itself (the users credentials are stored encrypted in the 3DS Admin UI database).

If the preferred mode of authentication is external, then OIDC-relevant data for the default organization and the method for resolving the OIDC configuration identifier must also be configured for the Admin UI:

The allowed values are either header or subdomain. The default value is subdomain, i.e. if not configured otherwise, the OIDC organization identifier will be resolved via the subdomain of the server from which the request originated, rather than via the 'x-nca3dss-orgsubdomain' attribute of the HTTP request header.

Find more information on the properties in the 3DS Admin Configuration Properties.

Different OIDC providers in a multi tenant setup

In a multi tenant setup, different organizations could have different configured OIDC providers. For this purpose, when the 3DS Admin runs in external authentication mode, the Organization Management tab is adapted to require the OIDC provider relevant inputs.

In a multi tenant setup, each organization will be accessible on a different subdomain, meaning each organization will have its own URL to access the 3DS Admin. For example, if there is an organization with name Netcetera and a subdomain assigned accordingly (‘netcetera’), then users of this organization can access the 3DS Admin on netcetera.<admin-host>:<admin-port>. The subdomain can differ from the organization name.

Besides a subdomain, the 3DS Admin requires configuring client ID, client secret, an issuer URL and a list of allowed roles for an organization. The client ID and the client secret are the credentials that the client application (the 3DS Admin) is given at the point when it is registered to the OIDC provider, while the issuer URL is a URL that uniquely identifies the OIDC provider. Finally, the 3DS Admin controls what roles can be assigned to users of this organization and for that purpose there is input for allowed roles.

Organization management with external iam

User management with external OIDC provider

If the preferred option of authentication is external, any OIDC provider can be chosen. The management of the OIDC provider and the users’ data management is left to the customer.

3DS Admin role based access control

The 3DS Admin allows the following roles to be assigned to a user:

  • ROLE_CONFIG_GENERAL_EDIT
  • ROLE_CONFIG_SCHEME_VIEW
  • ROLE_CONFIG_SCHEME_EDIT
  • ROLE_CONFIG_ACQUIRER_VIEW
  • ROLE_CONFIG_ACQUIRER_EDIT
  • ROLE_CONFIG_MERCHANT_VIEW
  • ROLE_CONFIG_MERCHANT_EDIT
  • ROLE_KEY_MANAGEMENT_VIEW
  • ROLE_KEY_MANAGEMENT_EDIT
  • ROLE_CONFIG_DIRECTORY_SERVER_VIEW
  • ROLE_CONFIG_DIRECTORY_SERVER_EDIT
  • ROLE_STATISTICS_VIEW
  • ROLE_TRANSACTION_SEARCH
  • AUTH_ADMIN
  • AUTH_SUPER_ADMIN

The explanation of each is given on the picture below:

Admin user management roles

If any other role is assigned to a user, the 3DS Admin will ignore it. The 3DS Admin also controls what roles are allowed per organization. If a user from a certain organization is assigned with a role which is not allowed by the organization configuration, the 3DS Admin will ignore that role.

The OIDC provider has to be configured to return the user roles in a custom claim inside the ID token. The name of the claim can be configured via the threedss.external-iam.default-organization-oidc-provider.roles_claim_name property.

Health status of the external OIDC providers

The 3DS Admin gives information about the health of the configured OIDC providers through the standard health endpoint. The health of the OIDC providers does not affect the overall health status, meaning some OIDC providers can be down but the overall 3DS Admin health stays up.

Switching authentication modes

The authentication mode of the Admin UI can be switched back and forth (between internal and external) at any time. In order the change to take effect, the 3DS Admin should be restarted.