Overwolf OpenID Connect (OIDC)

Overwolf OIDC (OpenID Connect) is an authentication protocol that lets you verify the identity of users attempting to gain access to endpoints protected by HTTPS. It is used to authenticate users who wish to access the Overwolf accounts system from applications or websites.

To use OIDC in your app you will first need to register your app. After you have registered your app, you can redirect your users to login authentication.

Registering your app

To use OIDC in your app, you need to register your app with the authorization server.

Use the OIDC registration endpoint to create your client.

OIDC Registration JSON

{
			"name": "oidc registration",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "Authorization",
						"value": "Bearer {accessToken}",
						"description": "Receive this from the DevRel."
					},
					{
						"key": "Content-Type",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\r\n    \"redirect_uris\": [\r\n        \"http://<your_auth_callback_redirect_url_1>\" ,\r\n        \"http://<your_auth_callback_redirect_url_2>\"\r\n    ],\r\n    \"post_logout_redirect_uris\": [\r\n        \"http://<your_logout_redirect_url_1>\",\r\n        \"http://<your_logout_redirect_url_2>\"\r\n    ],\r\n    \"client_name\": \"<display_name>\",\r\n    \"logo_uri\": \"https://<your_logo>.png\",\r\n    \"policy_uri\": \"https://<privacy_policy>\",\r\n    \"tos_uri\": \"https://<terms_of_service>\",\r\n}"
				},
				"url": {
					"raw": "https://id.overwolf.com/oidc/reg",
					"protocol": "https",
					"host": [
						"id",
						"overwolf",
						"com"
					],
					"path": [
						"oidc",
						"reg"
					]
				}

Registration Response example JSON

{
    "application_type": "web",
    "grant_types": [
        "refresh_token",
        "authorization_code"
    ],
    "id_token_signed_response_alg": "RS256",
    "post_logout_redirect_uris": [],
    "require_auth_time": false,
    "response_types": [
        "code"
    ],
    "subject_type": "public",
    "token_endpoint_auth_method": "client_secret_post",
    "introspection_endpoint_auth_method": "client_secret_post",
    "revocation_endpoint_auth_method": "client_secret_post",
    "require_signed_request_object": false,
    "request_uris": [],
    "client_id_issued_at": 1736697147,
    "client_id": "<your_client_id>",
    "client_name": "<your_client_name>",
    "client_secret_expires_at": 0,
    "client_secret": "<your_client_secret>",
    "logo_uri": "<your_logo_url>",
    "policy_uri": "<your_policy_url>",
    "redirect_uris": ["<your_redirect_url_1>", "<your_redirect_url_2>" ],
    "tos_uri": "<your_terms_of_service_url>",
    "registration_client_uri": "https://id.overwolf.com/oidc/reg/<client_id>",
    "registration_access_token": "<your_registration_access_token>" # this is a comment
}

Retrieving your data

To retrieve your client details, use https://id.overwolf.com/oidc/reg/{client_id}. You will need your client_id. The response will be the same as the registration response.

Updating your OIDC configuration

To update your client details, use the Update details endpoint below.

OIDC update details

{
			"name": "oidc reg update",
			"request": {
				"method": "PUT",
				"header": [
					{
						"key": "Authorization",
						"value": "Bearer {registrationAccessToken}",
						"type": "text"
					},
					{
						"key": "Content-Type",
						"value": "application/json",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\r\n    \"redirect_uris\": [\r\n        \"https://outplayed.tv/api/auth/callback\",\r\n        \"https://qa.outplayed.tv/api/auth/callback\",\r\n        \"http://idan.outplayed.tv:3000/api/auth/callback\"\r\n    ],\r\n    \"post_logout_redirect_uris\": [\r\n        \"https://outplayed.tv/api/auth/logout/callback\",\r\n        \"https://qa.outplayed.tv/api/auth/logout/callback\",\r\n        \"http://idan.outplayed.tv:3000/api/auth/logout/callback\"\r\n    ],\r\n    \"client_name\": \"Outplayed.tv login\",\r\n    \"logo_uri\": \"https://console-apps.overwolf.com/prod/apps/cghphpbjeabdkomiphingnegihoigeggcfphdofo/assets/74c5e169-958f-466c-99ff-34e781f05791.png\",\r\n    \"policy_uri\": \"https://www.overwolf.com/legal/privacy/\",\r\n    \"tos_uri\": \"https://www.overwolf.com/legal/terms/\",\r\n    \"client_id\": \"78o9chlccp9zsd7ix9z85vp91a7j68mu\"\r\n}"
				},
				"url": {
					"raw": "https://id.overwolf.com/oidc/reg/{clientId}",
					"protocol": "https",
					"host": [
						"id",
						"overwolf",
						"com"
					],
					"path": [
						"oidc",
						"reg",
						"{clientId}"
					]
				}

Using OIDC in your app

To use OIDC in your app:

1. Generate code verifier and code challenge.

JS Code generator and verifier

function generateCodeVerifier() {
  const randomArray = new Uint8Array(32);
  window.crypto.getRandomValues(randomArray);
  return btoa(String.fromCharCode(...randomArray))
    .replace(/=/g, '')
    .replace(/\+/g, '-')
    .replace(/\//g, '_');
}

generateCodeChallenge(codeVerifier: string): string {
  const hash = CryptoJS.SHA256(codeVerifier);
  const base64String = hash.toString(CryptoJS.enc.Base64);
  return base64String
    .replace(/=/g, '')
    .replace(/\+/g, '-')
    .replace(/\//g, '_');
}

2. You will need to redirect the user to the login page using the client id, code challenge, approved scopes, and authorization. This page returns an authorization code.

note

Include the offline_access scope to get a refresh token. This keeps the user logged in for more than one hour.

3. Use the returned authorization to create an access token. You will need to include the following:

• url params: code
• code verifier
• redirect uri
• basic authorization header with client id
• client secret Use the refreshToken param instead of the code and code verifier to keep the user logged in.

For example: Body:

const body = new URLSearchParams();
body.append('redirect_uri', redirectUri);

// For refreshing expired access token using refresh token
body.append('grant_type', 'refresh_token');
body.append('refresh_token', refreshToken);

// To get access token using auth code
body.append('grant_type', 'authorization_code');
body.append('code', code);
body.append('code_verifier', codeVerifier);

Headers:

{
  'Content-Type': `basic ${Buffer.from(`${process.env.OIDC_CLIENT_ID}:${process.env.OIDC_CLIENT_SECRET}`).toString('base64')}`
}

4. Use the access token to get the user profile. If this request fails with status 401, use the refresh token to get a new access token.
5. To log out, direct the user to logout url with the token id in the same browser where the user is currently logged in.