This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Authentication

1: Configure SSO with LDAP
2: Configure SSO with OIDC
3: Use federated identities with SDK
4: Use service accounts to automate workflows

1 - Configure SSO with LDAP

Authenticate your credentials with the W&B Server LDAP server. The following guide explains how to configure the settings for W&B Server. It covers mandatory and optional configurations, as well as instructions for configuring the LDAP connection from systems settings UI. it also provides information on the different inputs of the LDAP configuration, such as the address, base distinguished name, and attributes. You can specify these attributes from the W&B App UI or using environment variables. You can setup either an anonymous bind, or bind with an administrator DN and Password.

Only W&B Admin roles can enable and configure LDAP authentication.

Configure LDAP connection

Navigate to the W&B App.
Select your profile icon from the upper right. From the dropdown, select System Settings.
Toggle Configure LDAP Client.
Add the details in the form. Refer to Configuring Parameters section for details on each input.
Click on Update Settings to test your settings. This will establish a test client/connection with the W&B server.
If your connection is verified, toggle the Enable LDAP Authentication and select the Update Settings button.

Set LDAP an connection with the following environment variables:

Environment variable	Required	Example
`LOCAL_LDAP_ADDRESS`	Yes	`ldaps://ldap.example.com:636`
`LOCAL_LDAP_BASE_DN`	Yes	`email=mail,group=gidNumber`
`LOCAL_LDAP_BIND_DN`	No	`cn=admin`, `dc=example,dc=org`
`LOCAL_LDAP_BIND_PW`	No
`LOCAL_LDAP_ATTRIBUTES`	Yes	`email=mail`, `group=gidNumber`
`LOCAL_LDAP_TLS_ENABLE`	No
`LOCAL_LDAP_GROUP_ALLOW_LIST`	No
`LOCAL_LDAP_LOGIN`	No

See the Configuration parameters section for definitions of each environment variable. Note that the environment variable prefix LOCAL_LDAP was omitted from the definition names for clarity.

Configuration parameters

The following table lists and describes required and optional LDAP configurations.

Environment variable	Definition	Required
`ADDRESS`	This is the address of your LDAP server within the VPC that hosts W&B Server.	Yes
`BASE_DN`	The root path searches start from and required for doing any queries into this directory.	Yes
`BIND_DN`	Path of the administrative user registered in the LDAP server. This is required if the LDAP server does not support unauthenticated binding. If specified, W&B Server connects to the LDAP server as this user. Otherwise, W&B Server connects using anonymous binding.	No
`BIND_PW`	The password for administrative user, this is used to authenticate the binding. If left blank, W&B Server connects using anonymous binding.	No
`ATTRIBUTES`	Provide an email and group ID attribute names as comma separated string values.	Yes
`TLS_ENABLE`	Enable TLS.	No
`GROUP_ALLOW_LIST`	Group allowlist.	No
`LOGIN`	This tells W&B Server to use LDAP to authenticate. Set to either `True` or `False`. Optionally set this to false to test the LDAP configuration. Set this to true to start LDAP authentication.	No

2 - Configure SSO with OIDC

W&B Server’s support for OpenID Connect (OIDC) compatible identity providers allows for management of user identities and group memberships through external identity providers like Okta, Keycloak, Auth0, Google, and Entra.

OpenID Connect (OIDC)

W&B Server supports the following OIDC authentication flows for integrating with external Identity Providers (IdPs).

Implicit Flow with Form Post
Authorization Code Flow with Proof Key for Code Exchange (PKCE)

These flows authenticate users and provide W&B Server with the necessary identity information (in the form of ID tokens) to manage access control.

The ID token is a JWT that contains the user’s identity information, such as their name, username, email, and group memberships. W&B Server uses this token to authenticate the user and map them to appropriate roles or groups in the system.

In the context of W&B Server, access tokens authorize requests to APIs on behalf of the user, but since W&B Server’s primary concern is user authentication and identity, it only requires the ID token.

You can use environment variables to configure IAM options for your Dedicated cloud or Self-managed instance.

To assist with configuring Identity Providers for Dedicated cloud or Self-managed W&B Server installations, follow these guidelines to follow for various IdPs. If you’re using the SaaS version of W&B, reach out to support@wandb.com for assistance in configuring an Auth0 tenant for your organization.

Follow the procedure below to set up AWS Cognito for authorization:

First, sign in to your AWS account and navigate to the AWS Cognito App.
Provide an allowed callback URL to configure the application in your IdP:
- Add http(s)://YOUR-W&B-HOST/oidc/callback as the callback URL. Replace YOUR-W&B-HOST with your W&B host path.
If your IdP supports universal logout, set the Logout URL to http(s)://YOUR-W&B-HOST. Replace YOUR-W&B-HOST with your W&B host path.

For example, if your application was running at https://wandb.mycompany.com, you would replace YOUR-W&B-HOST with wandb.mycompany.com.

The image below demonstrates how to provide allowed callback and sign-out URLs in AWS Cognito.

wandb/local uses the implicit grant with the form_post response type by default.

You can also configure wandb/local to perform an authorization_code grant that uses the PKCE Code Exchange flow.
Select one or more OAuth grant types to configure how AWS Cognito delivers tokens to your app.
W&B requires specific OpenID Connect (OIDC) scopes. Select the following from AWS Cognito App:
- “openid”
- “profile”
- “email”
For example, your AWS Cognito App UI should look similar to the following image:

Select the Auth Method in the settings page or set the OIDC_AUTH_METHOD environment variable to tell wandb/local which grant to.

You must set the Auth Method to pkce.
You need a Client ID and the URL of your OIDC issuer. The OpenID discovery document must be available at $OIDC_ISSUER/.well-known/openid-configuration

For example, , you can generate your issuer URL by appending your User Pool ID to the Cognito IdP URL from the App Integration tab within the User Pools section:

Do not use the “Cognito domain” for the IDP URL. Cognito provides it’s discovery document at https://cognito-idp.$REGION.amazonaws.com/$USER_POOL_ID

Follow the procedure below to set up Okta for authorization:

Login to the Okta Portal at https://login.okta.com/.
On the left side, select Applications and then Applications again.
Click on “Create App integration.”
On the screen named “Create a new app integration,” select OIDC - OpenID Connect and Single-Page Application. Then click “Next.”
On the screen named “New Single-Page App Integration,” fill out the values as follows and click Save:
- App integration name, for example “Weights & Biases”
- Grant type: Select both Authorization Code and Implicit (hybrid)
- Sign-in redirect URIs: https://YOUR_W_AND_B_URL/oidc/callback
- Sign-out redirect URIs: https://YOUR_W_AND_B_URL/logout
- Assignments: Select Skip group assignment for now
On the overview screen of the Okta application that you just created, make note of the Client ID under Client Credentials under the General tab:
To identify the Okta OIDC Issuer URL, select Settings and then Account on the left side. The Okta UI shows the company name under Organization Contact.

The OIDC issuer URL has the following format: https://COMPANY.okta.com. Replace COMPANY with the corresponding value. Make note of it.

Login to the Azure Portal at https://portal.azure.com/.
Select “Microsoft Entra ID” service.
On the left side, select “App registrations.”
On the top, click “New registration.”

On the screen named “Register an application,” fill out the values as follows:
- Specify a name, for example “Weights and Biases application”
- By default the selected account type is: “Accounts in this organizational directory only (Default Directory only - Single tenant).” Modify if you need to.
- Configure Redirect URI as type Web with value: https://YOUR_W_AND_B_URL/oidc/callback
- Click “Register.”
- Make a note of the “Application (client) ID” and “Directory (tenant) ID.”
On the left side, click Authentication.
- Under Front-channel logout URL, specify: https://YOUR_W_AND_B_URL/logout
- Click “Save.”
On the left side, click “Certificates & secrets.”
- Click “Client secrets” and then click “New client secret.”
  
  On the screen named “Add a client secret,” fill out the values as follows:
  - Enter a description, for example “wandb”
  - Leave “Expires” as is or change if you have to.
  - Click “Add.”
- Make a note of the “Value” of the secret. There is no need for the “Secret ID.”

You should now have made notes of three values:

OIDC Client ID
OIDC Client Secret
Tenant ID is needed for the OIDC Issuer URL

The OIDC issuer URL has the following format: https://login.microsoftonline.com/${TenantID}/v2.0

Set up SSO on the W&B Server

To set up SSO, you need administrator privileges and the following information:

OIDC Client ID
OIDC Auth method (implicit or pkce)
OIDC Issuer URL
OIDC Client Secret (optional; depends on how you have setup your IdP)

Should your IdP require a OIDC Client Secret, specify it with the environment variable OIDC_SECRET.

You can configure SSO using either the W&B Server UI or by passing environment variables to the wandb/local pod. The environment variables take precedence over UI.

If you’re unable to log in to your instance after configuring SSO, you can restart the instance with the LOCAL_RESTORE=true environment variable set. This outputs a temporary password to the containers logs and disables SSO. Once you’ve resolved any issues with SSO, you must remove that environment variable to enable SSO again.

The System Console is the successor to the System Settings page. It is available with the W&B Kubernetes Operator based deployment.

Refer to Access the W&B Management Console.
Navigate to Settings, then Authentication. Select OIDC in the Type dropdown.
Enter the values.
Click on Save.
Log out and then log back in, this time using the IdP login screen.

Sign in to your Weights&Biases instance.
Navigate to the W&B App.
From the dropdown, select System Settings:
Enter your Issuer, Client ID, and Authentication Method.
Select Update settings.

If you’re unable to log in to your instance after configuring SSO, you can restart the instance with the LOCAL_RESTORE=true environment variable set. This outputs a temporary password to the containers logs and turn off SSO. Once you’ve resolved any issues with SSO, you must remove that environment variable to enable SSO again.

Security Assertion Markup Language (SAML)

W&B Server does not support SAML.

3 - Use federated identities with SDK

Use identity federation to sign in using your organizational credentials through W&B SDK. If your W&B organization admin has configured SSO for your organization, then you already use your organizational credentials to sign-in to the W&B app UI. In that sense, identity federation is like SSO for W&B SDK, but by using JSON Web Tokens (JWTs) directly. You can use identity federation as an alternative to API keys.

RFC 7523 forms the underlying basis for identity federation with SDK.

Identity federation is available in Preview for Enterprise plans on all platform types - SaaS Cloud, Dedicated Cloud, and Self-managed instances. Reach out to your W&B team for any questions.

For the purpose of this document, the terms identity provider and JWT issuer are used interchangeably. Both refer to one and the same thing in the context of this capability.

JWT issuer setup

As a first step, an organization admin must set up a federation between your W&B organization and a publicly accessible JWT issuer.

Go to the Settings tab in your organization dashboard
In the Authentication option, press Set up JWT Issuer
Add the JWT issuer URL in the text box and press Create

W&B will automatically look for a OIDC discovery document at the path ${ISSUER_URL}/.well-known/oidc-configuration, and try to find the JSON Web Key Set (JWKS) at a relevant URL in the discovery document. The JWKS is used for real-time validation of the JWTs to ensure that those have been issued by the relevant identity provider.

Using the JWT to access W&B

Once a JWT issuer has been setup for your W&B organization, users can start accessing the relevant W&B projects using JWTs issued by that identity provider. The mechanism for using JWTs is as follows:

You must sign-in to the identity provider using one of the mechanisms available in your organization. Some providers can be accessed in an automated manner using an API or SDK, while some can only be accessed using a relevant UI. Reach out to your W&B organization admin or the owner of the JWT issuer for details.
Once you’ve retrieved the JWT after signing in to your identity provider, store it in a file at a secure location and configure the absolute file path in an environment variable WANDB_IDENTITY_TOKEN_FILE.
Access your W&B project using the W&B SDK or CLI. The SDK or CLI should automatically detect the JWT and exchange it for a W&B access token after the JWT has been successfully validated. The W&B access token is used to access the relevant APIs for enabling your AI workflows, that is, to log runs, metrics, artifacts and so forth. The access token is by default stored at the path ~/.config/wandb/credentials.json. You can change that path by specifying the environment variable WANDB_CREDENTIALS_FILE.

JWTs are meant to be short-lived credentials to address the shortcomings of long-lived credentials like API keys, passwords and so forth. Depending on the JWT expiry time configured in your identity provider, you must continuously refresh the JWT and ensure that it’s stored in the file referenced by the environment variable WANDB_IDENTITY_TOKEN_FILE.

W&B access token also has a default expiry duration, after which the SDK or the CLI automatically try to refresh that using your JWT. If the user JWT has also expired by that time and is not refreshed, that could result in an authentication failure. If possible, the JWT retrieval and post-expiry refresh mechanism should be implemented as part of the AI workload that uses the W&B SDK or CLI.

JWT validation

As part of the workflow to exchange the JWT for a W&B access token and then access a project, the JWT undergoes following validations:

The JWT signature is verified using the JWKS at the W&B organization level. This is the first line of defense, and if this fails, that means there’s a problem with your JWKS or how your JWT is signed.
The iss claim in the JWT should be equal to the issuer URL configured at the organization level.
The sub claim in the JWT should be equal to the user’s email address as configured in the W&B organization.
The aud claim in the JWT should be equal to the name of the W&B organization which houses the project that you are accessing as part of your AI workflow. In case of Dedicated Cloud or Self-managed instances, you could configure an instance-level environment variable SKIP_AUDIENCE_VALIDATION to true to skip validation of the audience claim, or use wandb as the audience.
The exp claim in the JWT is checked to see if the token is valid or has expired and needs to be refreshed.

External service accounts

W&B has supported built-in service accounts with long-lived API keys for long. With the identity federation capability for SDK and CLI, you can also bring external service accounts that could use JWTs for authentication, though as long as those are issued by the same issuer which is configured at the organization level. A team admin can configure external service accounts within the scope of a team, like the built-in service accounts.

To configure an external service account:

Go to the Service Accounts tab for your team
Press New service account
Provide a name for the service account, select Federated Identity as the Authentication Method, provide a Subject, and press Create

The sub claim in the external service account’s JWT should be same as what the team admin configures as its subject in the team-level Service Accounts tab. That claim is verified as part of JWT validation. The aud claim requirement is similar to that for human user JWTs.

When using an external service account’s JWT to access W&B, it’s typically easier to automate the workflow to generate the initial JWT and continuously refresh it. If you would like to attribute the runs logged using an external service account to a human user, you can configure the environment variables WANDB_USERNAME or WANDB_USER_EMAIL for your AI workflow, similar to how it’s done for the built-in service accounts.

W&B recommends to use a mix of built-in and external service accounts across your AI workloads with different levels of data sensitivity, in order to strike a balance between flexibility and simplicity.

4 - Use service accounts to automate workflows

Manage automated or non-interactive workflows using org and team scoped service accounts

A service account represents a non-human or machine user that can automatically perform common tasks across projects within a team or across teams.

An org admin can create a service account at the scope of the organization.
A team admin can create a service account at the scope of that team.

A service account’s API key allows the caller to read from or write to projects within the service account’s scope.

Service accounts allow for centralized management of workflows by multiple users or teams, to automate experiment tracking for W&B Models or to log traces for W&B Weave. You have the option to associate a human user’s identity with a workflow managed by a service account, by using either of the environment variables WANDB_USERNAME or WANDB_USER_EMAIL.

Service accounts are available on Dedicated Cloud, Self-managed instances with an enterprise license, and enterprise accounts in SaaS Cloud.

Organization-scoped service accounts

Service accounts scoped to an organization have permissions to read and write in all projects in the organization, regardless of the team, with the exception of restricted projects. Before an organization-scoped service account can access a restricted project, an admin of that project must explicitly add the service account to the project.

An organization admin can obtain the API key for an organization-scoped service account from the Service Accounts tab of the organization or account dashboard.

To create a new organization-scoped service account:

Click New service account button in the Service Accounts tab of your organization dashboard.
Enter a Name.
Select a default team for the service account.
Click Create.
Next to the newly created service account, click Copy API key.
Store the copied API key in a secret manager or another secure but accessible location.

An organization-scoped service account requires a default team, even though it has access to non-restricted projects owned by all teams within the organization. This helps to prevent a workload from failing if the WANDB_ENTITY variable is not set in the environment for your model training or generative AI app. To use an organization-scoped service account for a project in a different team, you must set the WANDB_ENTITY environment variable to that team.

Team-scoped service accounts

A team-scoped service account can read and write in all projects within its team, except to restricted projects in that team. Before a team-scoped service account can access a restricted project, an admin of that project must explicitly add the service account to the project.

As a team admin, you can get the API key for a team-scoped service account in your team at <WANDB_HOST_URL>/<your-team-name>/service-accounts. Alternatively you can go to the Team settings for your team and then refer to the Service Accounts tab.

To create a new team scoped service account for your team:

Click New service account button in the Service Accounts tab of your team.
Enter a Name.
Select Generate API key (Built-in) as the authentication method.
Click Create.
Next to the newly created service account, click Copy API key.
Store the copied API key in a secret manager or another secure but accessible location.

If you do not configure a team in your model training or generative AI app environment that uses a team-scoped service account, the model runs or weave traces log to the named project within the service account’s parent team. In such a scenario, user attribution using the WANDB_USERNAME or WANDB_USER_EMAIL variables do not work unless the referenced user is part of the service account’s parent team.

A team-scoped service account cannot log runs to a team or restricted-scoped project in a team different from its parent team, but it can log runs to an open visibility project within another team.

External service accounts

In addition to Built-in service accounts, W&B also supports team-scoped External service accounts with the W&B SDK and CLI using Identity federation with identity providers (IdPs) that can issue JSON Web Tokens (JWTs).