Admin Console Gateway Installation and Configuration

The Admin Console Gateway is packaged as a single Docker image that you can deploy in your local environment or any cloud provider, such as Azure by Microsoft or Amazon’s AWS.

Pull the Docker Image

To deploy the Docker image, you need to log in to our Artifactory repository and pull the Docker image:

docker login wultra.jfrog.io
docker pull wultra.jfrog.io/wultra-docker/powerauth-cloud-admin-console-gw:${VERSION}

Configure the Docker Image

After you pull the Docker image in your own container repository, you need to prepare the env.list file with all the environment variables that are required or you want to configure. Please refer to the Admin Console Configuration Properties section for full reference.

PowerAuth Cloud service URL

Configure the PowerAuth Cloud service URL by setting the POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_POWERAUTH_CLOUD_SERVICE_URL environment variable.

POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_POWERAUTH_CLOUD_SERVICE_URL=http://pac-host/powerauth-cloud

Claim to retrieve external user id

By default, the Admin Console Gateway extracts the external user id from the received JWT claim unique_name. If this claim is not present in the JWT, the sub claim is used as default.

To override the default claim, use the POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_JWT_EXTERNAL_USER_ID_CLAIM environment variable.

POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_JWT_EXTERNAL_USER_ID_CLAIM=your_custom_claim

Claim to retrieve authenticated user roles

The Admin Console Gateway uses the roles retrieved from received JWTs for the RBAC. Depending on your OIDC provider / setup, the claim containing the roles may vary. By default, the Admin Console Gateway is configured to use the roles claim for this purpose.

To override the default claim, use the POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_SECURITY_AUTH_OIDC_ROLES_CLAIM_EXPRESSION environment variable and define the expression to match the desired claim (nested claims are also supported).

Custom top-level claim:

POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_SECURITY_AUTH_OIDC_ROLES_CLAIM_EXPRESSION=[your_custom_top_level_claim]

Custom nested claim:

POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_SECURITY_AUTH_OIDC_ROLES_CLAIM_EXPRESSION=[top_level][your_custom_nested_claim]

OIDC configuration

The OIDC Authorization Server configuration is required so that the incoming requests can be authenticated.

Use the POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_JWT_ISSUER_URI environment variable to configure your Authorization Server URI (this property is mandatory and is not defined by default). The configured URI is used to:

• Verify the iss claim of the received JWT (the configured value must match the value of the iss claim).
• To get the information necessary to retrieve the issuer public keys used for the JWT verification.

POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_JWT_ISSUER_URI=https://your-authorization-server/issuer

If the Authorization Server does not support any of the above-mentioned endpoints, or you want to specify the public key endpoint URI directly, you can use the SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI environment variable.

SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI=https://your-authorization-server/certs

If the SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI environment variable is defined, the POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_JWT_ISSUER_URI environment variable is still mandatory but in this case, its value is used only for the iss claim verification.

By default, the aud claim of the received JWT is not verified. To enable the verification, set the POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_JWT_AUDIENCES environment variable to the value expected in the aud claim.

POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_JWT_AUDIENCES=expected_audience_claim

Downstream security configuration

Requests routed by the Admin Console Gateway to the PowerAuth Cloud must be authenticated. The only authentication method currently supported by the Admin Console Gateway is the HTTP Basic Authentication and it is enabled by default.

Set the following two mandatory environment variables to complete the HTTP Basic Authentication configuration:

POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_SECURITY_DOWNSTREAM_AUTH_BASIC_USERNAME=username
POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_SECURITY_DOWNSTREAM_AUTH_BASIC_PASSWORD=password

If, for any reason, you want to disable the downstream HTTP Basic Authentication, use the following environment variable:

POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_SECURITY_DOWNSTREAM_AUTH_TYPE=NONE

Start the Docker Container

After you prepare the configuration file, you can run the image using docker run:

docker run --env-file env.list -d -it -p 8080:8080 \
    --name=pac-gateway wultra.jfrog.io/wultra-docker/powerauth-cloud-admin-console-gw:${VERSION}

This will launch the Docker container with the properties you specified.

You can now open http://localhost:8080/ and the home page shall be displayed.