2. Authentication and Identity
The API requires an OAuth2 JSON Web Token (JWT) that conforms to the OpenID Connect specification to determine client and user access. The project web application requires the Authorization Code Flow with Proof Key for Code Exchange (PKCE) flavor of OAuth 2.0. To support users that wish to develop their own utilities, we also suggest enabling the Device Authorization Grant Flow.
STIG Manager OSS has been tested to work with Keycloak, Okta, F5, and Azure Entra ID as OIDC providers. It is expected to work with other OIDC providers if they can be configured to provide a token that meets the requirements specified below. Please create an Issue with details on our GitHub project if you experience issues with other providers.
Note
If you are using the demonstration Keycloak container from the Project’s Docker Hub page, you may not need to change any settings or variables described in this section.
2.1. JSON Web Token (JWT) Requirements
The JWT produced by the Identity Provider should provide the claims specified below. Some of them may have different names in your configuration, and can be specified in STIGMan’s environment variables if they differ from the default values:
Username -
STIGMAN_JWT_USERNAME_CLAIM- default:preferred_usernameUser Full Name -
STIGMAN_JWT_NAME_CLAIM- (optional) default:nameUser Email -
STIGMAN_JWT_EMAIL_CLAIM- (optional) default:User Privileges -
STIGMAN_JWT_PRIVILEGES_CLAIM- default:realm_access.rolesScope -
STIGMAN_JWT_SCOPE_CLAIMdefault:scope. Some OIDC Providers (Okta, Azure Entra ID) use the claimscpto enumerate scopes. May name more than one claim, as a comma-separated list such asscp,roles, in which case the scopes found in each named claim are combined. See Service Account Client Setup.Assertion ID -
STIGMAN_JWT_ASSERTION_CLAIMdefault:jti. Some OIDC Providers (ADFS, Azure Entra ID) use the claimutiinstead ofjtito protect against replay attacks.Service Name -
STIGMAN_JWT_SERVICENAME_CLAIM- default:clientId. Used for service account clients.Audience -
STIGMAN_JWT_AUD_VALUE- (optional) no default. If specified, theaudclaim must include this value.
Important
Claim Value Formats
The token values found at each claim location must use the following formats:
Username, Name, Email, Assertion ID, Service Name: String
Scope: A space-separated string per OAuth 2.0 RFC 6749 (e.g.,
"openid stig-manager:collection stig-manager:stig:read"), or an array of strings with one scope per element (e.g.,["stig-manager:collection", "stig-manager:stig:read"]). Array elements are not split on spaces. WhenSTIGMAN_JWT_SCOPE_CLAIMnames more than one claim, each claim is read independently and may use either format.Privileges: An array of strings (e.g.,
["admin", "create_collection"]) ornull.Audience: String or array of strings. If
STIGMAN_JWT_AUD_VALUEis set, it must be present in theaudclaim value.
Note
STIG Manager will use the value specified in the STIGMAN_JWT_USERNAME_CLAIM environment variable as the Claim that should hold a User’s unique username. This value defaults to the Keycloak default, which is preferred_username
{
"exp": 1695154418,
"iat": 1630360166,
"auth_time": 1630354418,
"jti": "5b17970e-428a-4b54-a0bd-7ed29a436803",
"iss": "http://localhost:8080/auth/realms/stigman",
"aud": [
"realm-management",
"account"
],
"sub": "eb965d15-aa78-43fc-a2a6-3d86258c1eec",
"typ": "Bearer",
"azp": "stig-manager",
"nonce": "2a6a0726-6795-47f5-88a6-00eb8aed9e23",
"session_state": "dca9233f-3d5b-4237-9e6e-be52d90cebdc",
"acr": "0",
"realm_access": {
"roles": [
"create_collection",
"admin",
"user"
]
},
"resource_access": {
"realm-management": {
"roles": [
"view-users",
"query-groups",
"query-users"
]
},
"account": {
"roles": [
"manage-account",
"manage-account-links",
"view-profile"
]
}
},
"scope": "openid stig-manager:collection stig-manager:stig:read stig-manager:user:read stig-manager:op stig-manager:user stig-manager:stig",
"email_verified": false,
"preferred_username": "Jane Stigsdottir"
}
The fields highlighted in the sample token above control the access and information STIG Manager requires to allow users to access the application. The token your OIDC provider creates does not need to look exactly like this, but where it differs the relevant claims must be specified using STIG Manager Environment Variables.
2.1.1. Cross-Origin Resource Sharing (CORS)
If your deployment environment has your OIDC Provider and the STIGMan Client in different origins (ie. domains), you will need to specify the Client origin in the Web Origins configuration options of your OIDC Provider. This will set the Access-Control-Allow-Origin header in the OIDC Provider’s responses, and permit browsers to make subsequent requests to the OIDC provider.
Alternatively, you could situate your OIDC Provider and the Client server behind a reverse proxy that is configured to present them both as coming from the same origin, avoiding the problem.
2.1.2. Service Account Client Setup
If you are using a service account to connect to the STIGMan API, the STIGMAN_JWT_SERVICENAME_CLAIM Environment Variable must specify the claim that will hold the client ID. The default is clientId. There may be other OIDC Provider configuration required.
Some OIDC Providers convey a service account’s permissions in a different claim than they use for interactive users. Azure Entra ID is one: a token issued for a signed-in user carries delegated permissions in the scp claim, as a space-separated string, while a token issued through the client credentials flow carries the application’s own permissions in the roles claim, as an array of strings, and has no scp claim. Either claim may be absent entirely — an application with no app roles assigned receives no roles claim.
To accept both kinds of token, name both claims:
STIGMAN_JWT_SCOPE_CLAIM=scp,roles
STIG Manager combines the scopes found in each claim, so one deployment can serve interactive users and service accounts at the same time. Naming several claims is not specific to Entra ID and may be used with any provider that splits scopes across claims.
To grant an Entra ID service account access:
In the API’s app registration, define app roles whose value is a STIG Manager scope, such as
stig-manager:collection. Allowed member types must include Application. App role values may contain colons and must not contain spaces, so STIG Manager’s scope strings are valid role values. Entra emits them bare, without theapi://prefix.Assign those app roles to the calling application and grant admin consent.
Have the client request the scope
api://<application-id>/.default. The client credentials flow does not accept individual scopes.Set
STIGMAN_JWT_AUD_VALUEto the API’s client ID, since v2 tokens use it as the audience.
Note
On Entra ID the roles claim also carries a user’s assigned app roles. Naming roles therefore combines any app roles assigned to a user into that user’s scope set. Values that are not STIG Manager scopes cannot match a required scope and are ignored. Privileges remain a separate setting, read from STIGMAN_JWT_PRIVILEGES_CLAIM.
Note
An Entra ID administrator may alternatively emit a fixed scope string into a custom claim using a claims mapping policy, and point STIGMAN_JWT_SCOPE_CLAIM at it. This requires no change to STIG Manager, but the value is a constant attached to the API, so every caller receives the same scopes and per-user consent no longer governs the scope set. It also requires either acceptMappedClaims in the application manifest, which needs a verified-domain Application ID URI and is single-tenant only, or a custom signing key. Assigning app roles as described above is preferred.
2.2. Scopes and Privileges
The STIG Manager API restricts endpoint access using the “scope” claims in the JWT. See the API specification for details.
The guide provided below maps scopes to various Realm Roles that are then assigned to Users. These Roles and Scopes can be provided to users in various ways, using Client Roles, Client Groups, defaults, etc. Please refer to the Keycloak Documentation for more information.
The Roles specified in the JWT map to Privileges in STIG Manager that allow varying levels of access and abilities. See the Configure Users section of the Setup Guide for more information.
The Scopes specified in the JWT control access to API endpoints as specified in the OpenAPI spec. See the STIG Manager Client Scopes and Roles table below for a suggestion on how to allocate these scopes using OIDC roles, and more information.
If your OIDC Provider requires the STIG Manager Web App to request additional scopes when redirecting to the OIDC Provider, you can provide those as values to the envvar STIGMAN_CLIENT_EXTRA_SCOPES. An example would be Okta, which requires the scope offline_access be requested in order to generate a refresh token.
2.3. Authentication Example - RedHat Keycloak 19
Note
The Keycloak project updates frequently, and may introduce changes that will make this guide incompatible with later versions. The information provided below is just one way to configure Keycloak 19 to provide a JWT that will work with STIG Manager. Please make sure you configure Keycloak in accordance with your organization’s Security Policy.
The web client is an OpenID Connect (OIDC) OAuth2 Relying Party and the API is an OAuth2 Resource Server. User authentication is provided by an external Identity Provider (IdP). All API access is controlled by OAuth2 JSON Web Tokens (JWTs) issued by the IdP. User privileges are extracted from token claims and endpoint access is controlled by token scope. Keycloak is readily available, actively maintained by a major OSS vendor, supports Identity Brokering and User Federation, and is used by major DoD projects such as Air Force Iron Bank. Keycloak supports many External Identity Providers, but has only been tested using its own authentication. More information about RedHat Keycloak.
A sample Docker-compose orchestration, using a Keycloak image configured as specified below and containing Demo users, can be found on our Docker Hub page.
2.3.1. Keycloak 19 Configuration
The configuration offered below is just one way to create a Keycloak Realm that will authenticate Users for the STIGMan API and Client. The following items in the Keycloak installation must be created and configured appropriately, and their values passed to STIG Manager in the appropriate Environment Variable:
Keycloak Realm - suggested value: stigman
Client ID - suggested value: stig-manager
Keycloak settings for the “stigman” realm:
Configure->Roles->Realm Roles - Add the following roles:
user
create_collection
admin
Note
These roles can also be set up at the Client level, rather than the Realm level. Make adjustments accordingly.
Configure->Roles->Default Roles - Recommended: set “user” and “create_collection” as default roles.
Configure->Client Scopes - Create the following scopes, and assign them the specified roles in that scope’s “Scope” tab (Role assignment only required if using Roles to assign scopes, rather than setting them as Default Client Scopes):
STIG Manager Client Scopes and Roles: Client Scopes
Roles
stig-manager:collection
user, admin
stig-manager:collection:read
user
stig-manager:op
admin
stig-manager:op:read
user
stig-manager:stig
admin
stig-manager:stig:read
user
stig-manager:user
user, admin
stig-manager:user:read
user
stig-manager
Alternative catch-all scope for all roles above.
Configure->Clients->stig-manager:
Settings:
Enable Authorization Code Flow with PKCE (Called “Standard Flow” in Keycloak)
Valid Redirect URIs - The URI at which your users will access STIG Manager, and the re-authentication page beside it. For a deployment at
https://stigman.example.com/, register these exact URIs:https://stigman.example.com/andhttps://stigman.example.com/reauth.htmlfor the web apphttps://stigman.example.com/client-v2/andhttps://stigman.example.com/client-v2/reauth.htmlfor the next-generation web app
Behind a reverse proxy that serves STIG Manager under a path, include that path, for example
https://example.com/stigman/client-v2/. The next-generation web app always returns toclient-v2/after sign-in, then reopens the page the user asked for, so no wildcard is needed.Web Origins - Configure according to Organizational requirements. Often the same as the Valid Redirect URIs
Client Scopes:
Add the scopes created above as either Assigned Optional Client Scopes or Default Client Scopes.
Other suggested Keycloak settings for the stig-manager client:
Revoke refresh token: yes
Refresh Token Max Reuse: 0
Client or SSO Session Idle: 10 minutes
The “preferred_username” claim in the token should hold the username you intend to be used in STIG Manager (this is the default setting). If changed, use
STIGMAN_JWT_USERNAME_CLAIMto specify.Set “OAuth 2.0 Device Authorization Grant Enabled” to “On.”
For other settings, the default Keycloak settings should work.
2.3.2. Configure STIG Manager to use your Authentication provider
Most commonly, STIG Manager will require the below Environment Variable to be specified, unless their default values are appropriate. Check the Environment Variables document for an exhaustive list of Environment Variables and their default values.
STIGMAN_OIDC_PROVIDER- Sample value:http://localhost:8080/auth/realms/stigman- The base URL of the OIDC provider issuing signed JWTs for the API. The string/.well-known/openid-configurationwill be appended when fetching metadata.
STIGMAN_CLIENT_OIDC_PROVIDER- Default value: Value ofSTIGMAN_OIDC_PROVIDER- Client override of the base URL of the OIDC provider issuing signed JWTs for the API. The string/.well-known/openid-configurationwill be appended by the client when fetching metadata.
STIGMAN_CLIENT_ID- Suggested value:stig-manager
STIGMAN_JWT_PRIVILEGES_CLAIM- Sample value:realm_access.roles
STIGMAN_CLIENT_EXTRA_SCOPES- Sample value:offline_access
A sample Keycloak image, recommended only for testing purposes, is available on Docker Hub. Most of the default values for the above Environment variables will work with this image.
2.4. STIGMAN_CLIENT_REAUTH_ACTION
The STIGMAN_CLIENT_REAUTH_ACTION environment variable controls how the STIG Manager web application responds when a user’s credentials have expired and re-authentication is required. This setting determines where and how the OIDC (OpenID Connect) authorization flow is initiated for the user.
2.4.1. Possible Values
- popup (default)
Opens the OIDC authorization endpoint in a new browser popup window.
- iframe
Opens the OIDC authorization endpoint in an embedded iframe within the app.
- tab
Opens the OIDC authorization endpoint in a new browser tab.
- reload
Reloads the current application tab, which will trigger the authentication redirect.
2.4.2. Comparison Table
Action |
UX |
Upsides |
Downsides |
|---|---|---|---|
popup |
Good |
|
May be blocked by third-party browser popup blockers, requiring user intervention. |
iframe |
Best |
|
The OIDC Provider must allow being embedded in an iframe by setting an appropriate |
tab |
Acceptable |
|
User will be switched back to the original tab after authentication, which can be confusing if multiple tabs are open. |
reload |
Poor |
|
The application state is lost; any unsaved work will be discarded. |