Admin Console Installation and Configuration

This guide covers installation and configuration of the two Admin Console components:

• Admin Console Gateway (backend): A Spring-based API that authenticates incoming requests with OIDC/JWT and proxies authorized calls to PowerAuth Cloud.
• Admin Console (SPA) (frontend): A Single Page Application that users access in the browser. It authenticates users with OAuth2/OIDC Authorization Code with PKCE and calls the Gateway.

Follow the sections below to deploy both components and ensure their OAuth/OIDC configuration is aligned.

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.

Admin Console (SPA) Installation and Configuration

The Admin Console user interface is a standalone Single Page Application (SPA) packaged as a Docker image. It renders the UI and communicates with the Admin Console Gateway.

Refer to the Admin Console Configuration Properties for full reference of all UI environment variables.

Pull the Docker Image

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

Configure the Docker Image

At runtime, the SPA reads its configuration from environment variables and inlines them into static assets. Create an env.list file with values suitable for your environment. The most important settings are:

• API_URL — Base URL of the Admin Console Gateway
• OAUTH_* — OAuth2/OIDC settings for authenticating users in the SPA

Example env.list:

# URL of the Admin Console Gateway (publicly reachable from user browsers)
API_URL=https://admin-console-gw

# Enable OAuth2/OIDC based login in the SPA
OAUTH_ENABLED=true

# Values below must match your Identity Provider (IdP) app configuration
OAUTH_CLIENT_ID=admin-console
OAUTH_SCOPE=api://aaa-bbb-ccc-111-222-333/.default

# Authorization endpoint and redirect back to the SPA after login
OAUTH_AUTHORIZE_URL=https://idp.example.com/oauth2/authorize
OAUTH_AUTHORIZE_REDIRECT_URL=https://admin-console/oauth/callback

# Token endpoint and redirect back to the SPA after token is processed
OAUTH_TOKEN_URL=https://idp.example.com/oauth2/token
OAUTH_TOKEN_REDIRECT_URL=https://admin-console/oauth/callback

Notes:

• Set redirect URLs to the public URL where the SPA is reachable (trailing slash is OK). Make sure the same redirect URI is registered in your IdP.
• API_URL must point to the Gateway base URL (not directly to PowerAuth Cloud). Use HTTPS in production.

PKCE is required for the SPA

The Admin Console SPA is a public client and uses the OAuth 2.1 Authorization Code flow with PKCE (S256). Ensure the following in your Identity Provider (IdP):

• PKCE must be enabled/allowed for the client application used by the SPA.
• Do not use the implicit flow. Only Authorization Code with PKCE is supported.
• Do not configure or require a client secret for the SPA. The token endpoint must accept the code_verifier and not require client authentication for this SPA client.
• Make sure the exact redirect URIs you configure in OAUTH_AUTHORIZE_REDIRECT_URL and OAUTH_TOKEN_REDIRECT_URL are registered for the SPA client in the IdP.

Azure Entra ID specifics:

• Use the “Single-page application (SPA)” platform for redirect URIs in the SPA app registration. This enables Authorization Code with PKCE automatically; no client secret is used.
• Do not enable the legacy implicit grant.

Important: Align SPA OAuth with Gateway OIDC/JWT verification

The tokens acquired by the SPA must be acceptable to the Admin Console Gateway. Ensure that:

• The IdP issuer used by the Gateway (POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_JWT_ISSUER_URI) matches the issuer of tokens obtained by the SPA.
• If the Gateway is configured to verify audiences (POWERAUTH_CLOUD_ADMIN_CONSOLE_GATEWAY_JWT_AUDIENCES), the tokens issued for the SPA must contain an aud claim matching this value. In many IdPs this corresponds to the resource identifier or API audience configured for the Gateway. Adjust OAUTH_CLIENT_ID/application settings in the IdP accordingly so that the resulting token’s audience meets the Gateway expectation.
• Token signing keys/JWKS published by the IdP are reachable by the Gateway (via issuer discovery or SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI).

For details, see Gateway Configuration Properties.

Start the Docker Container

Run the SPA container and expose it on a public port. The image serves the static files using NGINX on port 80 inside the container.

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

You can now open http://localhost:8081/ and the Admin Console UI should load. When you sign in, the SPA will obtain an access token from your IdP and call the Admin Console Gateway at the API_URL you configured.