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
- Get an initial registration token from your DevRel
- 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:
- Generate a code verifier.
- Hash the code verifier to get a code challenge.
- Save the code verifier for later use.
- 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>
- 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");
}
});
- 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;
}
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.