Overwolf OpenID Connect (OIDC)

Overwolf has created an SSO server that enables third party apps/sites to obtain limited access to Overwolf user accounts and allows your app users to login to your service. This server implements the OAuth2 protocol for authorization and the OpenID Connect (OIDC) identity layer for authentication.

The server exposes a discovery document. The server uses Proof Key for Code Exchange (PKCE) for authorization.

PKCE authorization code flow

Possible scopes:

• openid—the minimum scope, returns the Overwolf user's id (sub claim)
• email—request to get the Overwolf user's email
• profile—request to get the Overwolf profile details (i.e. username, nickname, picture)
• offline_access—requests a refresh token to allow the client to obtain new access toke ns without user interaction.
• subscriptions—request to get the Overwolf user's subscription details of your service

Registering your OAuth app

1. Get an initial registration token from your DevRel
2. Send registration requests to [https://id.overwolf.com/oidc/reg](https://id.overwolf.com/oidc/reg)

POST /oidc/reg HTTP/1.1
Host: id.overwolf.com
Content-Type: application/json
Authorization: Bearer <initial registration token>

{
  "redirect_uris": [
    "http://<your_auth_callback_redirect_url_1>",  
    "http://<your_auth_callback_redirect_url_2>"
   ],
   "post_logout_redirect_uris": [
      "http://<your_logout_redirect_url_1>",
      "http://<your_logout_redirect_url_2>"
   ],
   "client_name": "<display_name>",
   "logo_uri": "https://<your_logo>.jpg",
   "policy_uri": "https://<privacy_policy>",
   "tos_uri": "https://<terms_of_service>"
 }

The response will include your client id, client secret and registration access token. Save your registration access token in a safe place.

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
}

Managing your OAuth app

Use the following sections to manage your OAuth app.

Get client details

To get your client details use the following:

GET /oidc/reg/<your_client_id> HTTP/1.1
Host: id.overwolf.com
Authorization: Bearer <registration access token>

Update client details

To Update your client details use the following:

PUT /oidc/reg/<your_client_id>  HTTP/1.1
Host: id.overwolf.com
Content-Type: application/json
Authorization: Bearer <registration access token>

{
  "redirect_uris": [
    "http://<your_auth_callback_redirect_url_1>",  
    "http://<your_auth_callback_redirect_url_2>"
   ],
   "post_logout_redirect_uris": [
      "http://<your_logout_redirect_url_1>",
      "http://<your_logout_redirect_url_2>"
   ],
   "client_name": "<display_name>",
   "logo_uri": "https://<your_logo>.jpg",
   "policy_uri": "https://<privacy_policy>",
   "tos_uri": "https://<terms_of_service>"
 }

Using Overwolf OIDC with your service

To use OIDC with your app:

1. Generate a code verifier.
2. Hash the code verifier to get a code challenge.
3. Save the code verifier for later use.
4. Initiate the authorization code flow. You will redirect the user to https://id.overwolf.com/oidc/auth with the following parameters:

• response_type=code
• client_id=<YOUR_CLIENT_ID>
• redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback
• scope=openid%20profile
• code_challenge=<YOUR_CODE_CHALLENGE>
• code_challenge_method=S256
• state=<random string>

5. Exchange the code for an access token by sending a POST request to https://id.overwolf.com/oidc/token. The user will be redirected to your redirect_uri with a code url parameter.

POST /oidc/token HTTP/1.1
Host: id.overwolf.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=YOUR_AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code_verifier=YOUR_CODE_VERIFIER

Code example:

  const { code, state } = req.query;
  const codeVerifier = req.cookies.codeVerifier

  try {
    // Exchange the authorization code for an access token and refresh token
    const tokenResponse = await axios.post(config.tokenEndpoint, {
      grant_type: "authorization_code",
      code,
      redirect_uri: config.redirectUri,
      client_id: config.clientId,
      client_secret: config.clientSecret,
      code_verifier: codeVerifier
    });

    const { access_token, refresh_token } = tokenResponse.data;
    // Store tokens for subsequent requests
    req.session.accessToken = access_token;

    res.send("Authentication successful!");
  } catch (error) {
    res.status(500).send("Token exchange failed");
  }
});

6. Once you have the access token, use it to access protected resources based on the required scopes.

  const response = await axios.get("https://id.overwolf.com/oidc/me", {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
  return response.data;
}

important

You need to handle cases where the user does not authorize one or more of the scopes you requested. For example a user does not allow the subscriptions scope or email.