Authentication¶

This section describes how to configure authentication for VOR Stream.

For an overview of authentication in VOR Stream, see the reference architecture.

For information on how to update the secret for an identity provider, see the administration guide.

Adding an Identity Provider to VOR Stream¶

VOR Stream supports multiple identity providers for user authentication. To add an identity provider, add an entry to oidc_providers.yaml configuration file.

Tip

By default, the deployment looks for the oidc_providers.yaml file in the root of the inventory directory. You can override this location by setting the oidc_providers_file variable in the inventory file. A sample oidc_providers.yaml file is provided in the root of the installation package.

Sample oidc_providers.yaml entry

  - name: azure
    email_claim: email
    first_name_claim: given_name
    groups_claim: groups
    last_name_claim: family_name
    user_claim: sub
    client_id: 99a98aea-2bdb-441b-8c89-aa9bea1b75e3
    claim_mappings:
      given_name: first_name
      family_name: last_name
      email: email
    client_kwargs:
      scope: openid profile
    client_secret: fTygJNOUplXBpmu2pTSh-KTzEu_zcgEGAXxjpgWUfyA
    icon: simpleMicrosoftazure
    bar_color: "#0078D4"
    icon_background_color: "#0078D4"
    icon_foreground_color: white
    label: Azure
    server_metadata_url: https://login.microsoftonline.com/653885fc-81f9-4002-9d75-7a87318a0623/v2.0
    staff_groups:
      - 4cc7056c-b2ec-4e5d-a88e-f2663d92e2c5 # All Employees Group
    superuser_groups:
      - 2fb87075-8a33-4272-86bb-0fa85e456c68 # Administrators Group
    mirror_groups: true # (1)!
    default_groups:
      - VOR Users # (2)!
      - VOR Modeling Users # (3)!
    groups_claim_mappings:
      "58afd5bf-c4dd-4885-89ca-43cdeb281329": # (4)!
        - VOR Power Users
        - Custom VOR Group 1
      "6e90eda1-4461-4b6e-8748-0db69a79764a": # (5)!
        - VOR Administrators
        - Custom VOR Group 2

Removes users from all existing application groups upon login via the identity provider, ensuring that only groups assigned by default_groups and groups_claim_mappings are applied. This keeps application group memberships synchronized with the identity provider.
Automatically add users who log in via Azure to the VOR Users group.
Automatically add users who log in via Azure to the VOR Modeling Users group.
Automatically add members of Azure's 58afd5bf-c4dd-4885-89ca-43cdeb281329 group to VOR Power Users and Custom VOR Group 1.
Automatically add members of Azure's 6e90eda1-4461-4b6e-8748-0db69a79764a group to VOR Administrators and Custom VOR Group 2.

Identity Provider Configuration Options¶

Option	Required	Default	Description
`name`	Yes		The name of the identity provider. This value is used to generate callback URIs to VOR Stream and must be unique among the other identity providers. See redirect URIs.
`label`	No	`name` value	The label to display on the login screen for the identity provider. Renders as "Log in with <label>" on the login screen.
`server_metadata_url`	Yes		The URL to the identity provider's OpenID Connect discovery document. Note that this should be without the `.well-known/openid-configuration` portion of the URI. For example, https://auth0.us.auth0.com/.well-known/openid-configuration would be specified as `https://auth0.us.auth0.com/`
`client_id`	Yes		OAuth 2.0 Client Identifier valid at the Authorization Server.
`client_secret`	Yes		OAuth 2.0 Client Secret valid at the Authorization Server.
`client_kwargs`	Yes		`client_kwargs` as specified by the Authlib package. This is where OpenID scopes are requested. Specifying `scope: openid profile email` is sufficient for most deployments.
`icon`	Yes		The icon to display for the identity provider on the login screen. Any icon from the `ng-icons` library is available.
`bar_color`	Yes		The color of the login button bar for the identity provider on the login screen.
`icon_background_color`	Yes		The background color of the icon for the identity provider on the login screen.
`icon_foreground_color`	Yes		The foreground color of the icon for the identity provider on the login screen.
`user_claim`	No	username	The claim that contains the user's unique identifier. This will be used as the user ID the application. Most identity providers will recommend to use the `sub` claim to ensure a constant field is used for the user ID as using a claim like `email` can evolve.
`email_claim`	No	email	The claim that contains the user's email address. If an email claim is not present in the identity token, an email will not be associated with the user's account.
`first_name_claim`	No	given_name	The claim that contains the user's first name. If a first name claim is not present in the identity token, a first name will not be associated with the user's account.
`last_name_claim`	No	family_name	The claim that contains the user's last name. If a last name claim is not present in the identity token, a last name will not be associated with the user's account.
`groups_claim`	No	groups	The claim that contains the user's groups, which are used when mapping users to staff or superuser statuses based on their group membership.
`groups_claim_mappings`	No		A mapping of external group names from the identity provider to one or more application groups. Users from the defined external groups will be automatically added to the defined application groups upon login via the identity provider. Non-existent groups are ignored. Existing group memberships remain unchanged.
`claim_mappings`	No		A mapping of provider claims to Vault entity attributes. This is only necessary if these attributes need to appear in Vault, which isn't required for most use cases. See claim_mappings for more information.
`staff_groups`	No		A list of groups that should be granted staff status in the application. Note that this requires a groups claim to be present in the identity token. Groups must match exactly.
`superuser_groups`	No		A list of groups that should be granted superuser status in the application. Note that this requires a groups claim to be present in the identity token. Groups must match exactly.
`default_groups`	No		A list of groups that users will automatically be added to upon login via the identity provider. Non-existent groups are ignored. Existing group memberships remain unchanged.
`mirror_groups`	No	false	If set to `true`, all existing application group memberships for a user will be removed upon login via the identity provider, and only groups assigned by `default_groups` and `groups_claim_mappings` will be applied. This ensures that group memberships in the application always mirror those from the identity provider. Non-existent groups are ignored.

Registering VOR Stream with an Identity Provider¶

VOR Stream uses the OpenID Connect (OIDC) protocol to authenticate users. It is important to ensure that your chosen authentication provider is OIDC-compliant to guarantee seamless integration with VOR. This section provides instructions for setting up the authentication provider.

Requirements¶

Redirect URIs¶

Ensure the following redirect URIs are set up in your authentication provider.

Danger

Unless otherwise noted, omit port 443 from the redirect URI if it's being used. Nonstandard ports need to be defined in the redirect URI.

Info

Replace DJANGO_HOSTNAME, DJANGO_SSL_PORT, VAULT_HOSTNAME, VAULT_PORT, WEB_HOSTNAME, and WEB_SSL_PORT with the values for your environment. AUTH_PROVIDER_NAME is the name value you set for the provider in you oidc_providers.yaml file.

https://<DJANGO_HOSTNAME>:<DJANGO_SSL_PORT>/oauth/<AUTH_PROVIDER_NAME>/callback: authenticate to the Django admin interface
https://<WEB_HOSTNAME>:<WEB_SSL_PORT>/oidc/callback: authenticate to the VOR Stream CLI. For this URI, always include the exact port even if it is 443.
https://<VAULT_HOSTNAME>:<VAULT_PORT>/ui/vault/auth/<AUTH_PROVIDER_NAME>/oidc/callback: authenticate to the Vault UI
https://<WEB_HOSTNAME>:<WEB_SSL_PORT>/<AUTH_PROVIDER_NAME>/callback: authenticate to the VOR Stream UI

Required OIDC Claims and Scopes¶

The following OIDC scopes are required:

openid
profile

For the population of first and last names and email addresses in the application, the following OIDC standard claims are required to be present in the ID token:

email
family_name
given_name

Warning

If these claims are not present in the ID token, the info that the claim would have provided will not be populated in the application, which can make it difficult to identify users.

Tip

If the identity provider does not provide the required claims, it may be possible to add them as optional claims in the identity provider's configuration. The required information may also be present in other claims, which can be mapped to the attributes using the email_claim, first_name_claim, and last_name_claim options in the oidc_providers.yaml file (see Identity Provider Configuration Options for more details).

Example: Registering VOR with Microsoft Entra ID¶

Follow the steps outlined below for basic configuration of a Microsoft Entra ID app registration to use as an identity provider for VOR Stream. For detailed guidance, refer to the Microsoft documentation.

Add an application.
1. Navigate to the Azure Portal.
2. Click Microsoft Entra ID
3. Click App registrations.
4. Click New registration.
5. Enter a name for the application.
6. Select the supported account type. Currently, VOR Stream only supports single-tenant app registrations.
7. In the Redirect URI section create a new Web platform entry for each redirect URI.
8. Click Register.
Add claims to the ID token to help identify users in the application.
1. Navigate to Token configuration.
2. Select Add optional claim.
3. Select ID Token Type
4. Select the following claims:
  - email
  - family_name
  - given_name
5. Click Add.
  
  Note
  
  If required API permissions are not already granted, a prompt will appear that says "Some of these claims (email, family_name, given_name) require OpenID Connect scopes to be configured through the API permissions page or by checking the box below." Check the box and click Add.
If groups need to be added to the identity token for mapping to staff or superuser status, a groups claim must be added to the ID token.
1. Navigate to Token configuration.
2. Select Add groups claim.
3. Select the type of groups to be returned. Selecting "All groups" should work fine for most situations, but if there are a large number of groups, it may be desirable to restrict the groups returned to prevent a group overage.
  
  Info
  
  Setting "Groups assigned to the application" requires a Microsoft Entra ID P1 or P2 license.
On the Certificates & secrets page of the app, add a new client secret and note down the value after hitting Add. This will be the value of client_secret in the configuration.
Select the Overview page of the app for help in gathering other required configuration parameters.
1. The Application (client) ID is the client_id.
2. Click Endpoints to obtain the server_metadata_url from OpenID Connect metadata document. Be sure to strip /.well-known/openid-configuration from the end of the URL. For example, if the URL is https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration, the server_metadata_url is https://login.microsoftonline.com/{tenant-id}/v2.0.
3. The Client secret is the client_secret you noted down earlier.

Troubleshooting¶

Missing User Information (e.g., First Name, Last Name, and/or Email)¶

If you are not seeing user information (e.g., first name, last name, and/or email) in VOR Stream, verify that the identity provider is sending the required claims in the OpenID Connect ID token. If the claims are present, ensure that the claims are being mapped correctly in the oidc_providers.yaml file (see Identity Provider Configuration Options for more details).

Verify Claims in the ID Token¶

To check the claims in the ID token, enable additional logging in Vault to print the ID token to the logs. The ID token is a JSON Web Token (JWT) that contains the claims sent by the identity provider. The claims are base64 encoded and can be decoded using a tool like jwt.io.

Follow the steps below to enable additional logging in Vault to print the ID token to the logs:

SSH into the server running Vault.
Log in to Vault using the vault CLI and the root token.
Enable an additional log sink to print the ID token to the logs. This example command prints a raw log to /tmp/oidc_audit.log:
```
vault audit enable file file_path=/tmp/oidc_audit.log log_raw=true
```
Warning

The log file will contain sensitive information, including the ID token. Ensure that audit logging is disabled and the log file is removed after troubleshooting is complete.

Watch the log file for login attempts:

tail -f /tmp/oidc_audit.log | jq -R 'fromjson? | select(. != null and .time != null and .request.data.jwt != null) | { time: .time, jwt: .request.data.jwt }'

Tip

You will need to run this command as the service account running Vault or with elevated permissions to read the log file.

Attempt to log in to the VOR Stream UI using the identity provider in question. You should see output similar to the following streaming as login attempts are made:

{
   "time": "2024-05-08T07:23:00.869111964Z",
   "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IkwxS2ZLRklfam5YYndXYzIyeFp4dzFzVUhIMCJ9.eyJhdWQiOiJhNjJlODBjNS1kNjlmLTRiZjktYThjNS1mZWYyNDI2ZGEzZGYiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNDhkOGJkNzctZGE1Ni00ODMyLWFlMjgtY2JhMjEwNTdmNTE1L3YyLjAiLCJpYXQiOjE3MTUxNTI2ODAsIm5iZiI6MTcxNTE1MjY4MCwiZXhwIjoxNzE1MTU2NTgwLCJlbWFpbCI6ImhlbnJ5LnNraWJhQGZyZ3Jpc2suY29tIiwiZmFtaWx5X25hbWUiOiJTa2liYSIsImdpdmVuX25hbWUiOiJIZW5yeSIsIm5hbWUiOiJIZW5yeSBTa2liYSIsIm5vbmNlIjoiVWNRQU56R3NEbXV6QjA3ald4QkoiLCJvaWQiOiJiZDg1ODFjZC0yODk2LTQyYzEtOWNhZi02NzkwNDBjNzljMDYiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJoZW5yeS5za2liYUBmcmdyaXNrLmNvbSIsInJoIjoiMC5BUzBBZDczWVNGYmFNa2l1S011aUVGZjFGY1dBTHFhZjF2bExxTVgtOGtKdG85OHRBUEEuIiwic3ViIjoiWE1QYTZxQXo1SnJ3NS15eGJqeGxUOEdNeU0wUFdvNVB2S3JtajM0NkF6YyIsInRpZCI6IjQ4ZDhiZDc3LWRhNTYtNDgzMi1hZTI4LWNiYTIxMDU3ZjUxNSIsInV0aSI6IlpkWDhfYzZfWVVxVHVDRktVd3cxQUEiLCJ2ZXIiOiIyLjAifQ.hgsRn6Wn237ueYBr2K_Yi2SNe8JBlcjgdIfsMgp-rohkKiESeLHAoH-Fu4Ox9dZ-C13sXzajsvcRnqfGeKVUf9VFHWgN1HwsdGxgJgu2unmGDLgjnSSkx9lgO_8keumBgjs72KlJkmzbPmuUr6MTNJW_PhVwJxK4Veu5TgKZsoIdcMsXbYaHhlOhixfR8ZuxqgON9_7G7eGWUJxiT7jIn8A6ZbCJhTEWTRRfAPY_SLqQchOdjQUjx_hY3rqx-rRZQNW9EOu21PN0hcv_tNvvPyfZTanR39lISZKErK8m6GvlxNpT_oETBMKSYO8GKI1o3njuvhN-vuEU0z5HCLcyVA"
}

Copy the jwt value from the output and paste it into the jwt.io debugger to decode the ID token. Verify that the required claims are present in the decoded token. If they are not present, review the identity provider's configuration to ensure the claims are being sent.

Sample Decoded JWT Token

Troubleshooting Cleanup

After troubleshooting is complete, disable the additional logging and remove the log file (you may need to run these commands as the service account running Vault):

vault audit disable file
rm /tmp/oidc_audit.log