Skip to main content

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, '_');
}
  1. 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.

  1. Use the returned authorization to create an access token. You will need to include the following url parameters:
  • Code.
  • Code verifier.
  • Redirect uri.
  • Basic authorization header with client id and client secret.

Use the grant_type: <refresh_token> parameter with refreshToken params instead of authorization_code and code to keep the user logged in.

An 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);

Or use the following:

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

For the methods listed here you will need to use basic authorization such as <base64encode(client_id:client_secret)>.

An example header:

{
  'Content-Type': `basic ${Buffer.from(`${process.env.OIDC_CLIENT_ID}:${process.env.OIDC_CLIENT_SECRET}`).toString('base64')}`
}
  1. 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.
Retrieve user details
"/me": {
  "get": {
    "security": [
      {
        "basicAuth": []
      }
    ],
    "tags": [
      "client"
    ],
    "description": "Obtains information about the user from their Access Token",
    "externalDocs": {
      "description": "External link",
      "url": "https://overwolf.github.io"
    },
    "responses": {
      "200": {
        "description": "Test"
      },
      "401": {
        "description": "Invalid Token",
        "content": {
          "application/json": {
            "examples": {
              "example1": {
                "value": {
                  "error": "invalid_token",
                  "error_description": "invalid token provided"
                }
              }
            },
            "schema": {
              "type": "object",
              "required": [
                "error",
                "error_description"
              ],
              "properties": {
                "error": {
                  "type": "string",
                  "enum": [
                    "invalid_token"
                  ]
                },
                "error_description": {
                  "type": "string",
                  "enum": [
                    "invalid token provided"
                  ]
                }
              }
            }
          }
        }
      },
      "500": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "examples": {
              "example1": {
                "value": {
                  "statusCode": 500,
                  "message": "Internal Server Error"
                }
              }
            },
            "schema": {
              "type": "object",
              "required": [
                "statusCode",
                "message"
              ],
              "properties": {
                "statusCode": {
                  "type": "number",
                  "enum": [
                    500
                  ]
                },
                "message": {
                  "type": "string",
                  "enum": [
                    "Internal Server Error"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
},
  1. To log out, direct the user to logout url with the token id in the same browser where the user is currently logged in.
User logout
"/session/end": {
  "post": {
    "tags": [
      "client"
    ],
    "description": "Uses a user's `Id Token` to log them out from their local session (**must be opened in the users' browser where they logged in to properly erase the session!**)",
    "parameters": [
      {
        "$ref": "#/components/parameters/idTokenHint"
      },
      {
        "name": "post_logout_redirect_uri",
        "in": "query",
        "description": "The URI to redirect to once the logout is completed (Must be registered ahead of time)",
        "schema": {
          "type": "string",
          "format": "uri"
        }
      }
    ],
    "responses": {
      "302": {
        "description": "The logout operation was properly invoked, redirecting",
        "headers": {
          "location": {
            "$ref": "#/components/headers/location302"
          }
        }
      }
    }
  }
}