• Introduction to OAuth
• User owned applications
• Group owned applications
• Expiring access tokens
• Authorized applications
  • Troubleshooting

Configure WVS as an OAuth 2.0 authentication identity provider

This document describes how you can use WVS as an OAuth 2.0 authentication identity provider.

• OAuth 2 applications can be created and managed using the WVS Web-App (described below) or managed using the Applications API.
• After an application is created, external services can manage access tokens using the OAuth 2 API.
• To allow users to sign in to WVS using third-party OAuth 2 providers, see OmniAuth documentation.

Introduction to OAuth

OAuth 2 provides to client applications a ‘secure delegated access’ to server resources on behalf of a resource owner. OAuth 2 allows authorization servers to issue access tokens to third-party clients with the approval of the resource owner or the end-user.

OAuth 2 can be used:

• To allow users to sign in to your application with their WVS.io account.
• To set up WVS.io for authentication to your WVS instance. See WVS OmniAuth.

The ‘WVS Importer’ feature also uses OAuth 2 to give access to repositories without sharing user credentials to your WVS.io account.

WVS supports several ways of adding a new OAuth 2 application to an instance:

• User owned applications
• Group owned applications
• Instance-wide applications

The only difference between these methods is the permission levels. The default callback URL is http://your-wvs.example.io/users/auth/wvs/callback.

User owned applications

To add a new application for your user:

1. In the top-right corner, select your avatar.
2. Select Edit profile.
3. On the left sidebar, select Applications.
4. Enter a Name, Redirect URI and OAuth 2 scopes as defined in Authorized Applications. The Redirect URI is the URL where users are sent after they authorize with WVS.

5. Select Save application. WVS provides:

   • The OAuth 2 Client ID in the Application ID field.
   • The OAuth 2 Client Secret, accessible:
     • In the Secret field.
     • Using the Copy button on the Secret field

Group owned applications

To add a new application for a group:

1. Navigate to the desired group.
2. On the left sidebar, select Settings > Applications.
3. Enter a Name, Redirect URI and OAuth 2 scopes as defined in Authorized Applications. The Redirect URI is the URL where users are sent after they authorize with WVS.

4. Select Save application. WVS provides:

   • The OAuth 2 Client ID in the Application ID field.
   • The OAuth 2 Client Secret, accessible:
     • In the Secret field.
     • Using the Copy button on the Secret field

Expiring access tokens

All existing integrations should be updated to support access token refresh.

Access tokens expire in two hours which means that integrations that use them must support generating new access tokens at least every two hours. Existing:

• Applications can have expiring access tokens:
  1. Edit the application.
  2. Select Expire access tokens.
• Tokens must be revoked or they don’t expire.

When applications are deleted, all grants and tokens associated with the application are also deleted.

Authorized applications

Every application you authorize with your WVS credentials is shown in the Authorized applications section under Settings > Applications.

The WVS OAuth 2 applications support scopes, which allow various actions that any given application can perform. Available scopes are depicted in the following table.

Scope	Description
api	Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry.
read_user	Grants read-only access to the authenticated user’s profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
read_api	Grants read access to the API, including all groups and projects, the container registry, and the package registry.
read_repository	Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API.
write_repository	Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API).
read_registry	Grants read-only access to container registry images on private projects.
write_registry	Grants read-only access to container registry images on private projects.
sudo	Grants permission to perform API actions as any user in the system, when authenticated as an administrator user.
openid	Grants permission to authenticate with WVS using OpenID Connect. Also gives read-only access to the user’s profile and group memberships.
profile	Grants read-only access to the user’s profile data using OpenID Connect.
email	Grants read-only access to the user’s primary email address using OpenID Connect.

At any time you can revoke any access by clicking Revoke.

Troubleshooting

For Additional Support, Please reach out to us on our Discord or by Email.