# OAuth2

## OAuth2 Auth Scheme Anatomy

OAuth2 Auth Schemes are comprised of:

* the Scheme name
* a Validation URL, which Elements will use to validate the token it receives
* the Response Id Mapping, which Elements will use to get the user id from the validation request (see below for example)
* a list of Headers and a list of Parameters for the validation request, which can be predefined, or sent from the client and filled in by Elements before making the validation request

<figure><img src="https://591056737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSwaCRaceHc67DqQUJ3ZN%2Fuploads%2FQ0T5hNSRPuLzGtofYbEB%2FScreenshot%202025-04-04%20at%204.22.25%E2%80%AFPM.png?alt=media&#x26;token=b799557b-2c7a-48e5-8ff6-fc20bd0919b6" alt=""><figcaption></figcaption></figure>

<figure><img src="https://591056737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSwaCRaceHc67DqQUJ3ZN%2Fuploads%2FPRII66fbCMJSRIWkEHUY%2FScreenshot%202025-04-04%20at%204.36.03%E2%80%AFPM.png?alt=media&#x26;token=e77945f2-afe4-4c38-9530-507e4beb994d" alt=""><figcaption></figcaption></figure>

## Steam Example

One of the default OAuth2 Auth Schemes is for authenticating via Steam. We'll use this as an example as to how these can be used.

{% hint style="info" %}
It will be necessary to have a registered application on Steam, as this process will require an application id.
{% endhint %}

The goal here is to have our client application retrieve an auth ticket from Steam, then to send that to Elements, which in turn will use the ticket to verify the corresponding user id.

{% hint style="info" %}
This assumes that you already have a process set up to retrieve the auth ticket, either manually as depicted in the [Steam documentation](https://partner.steamgames.com/doc/features/auth#client_to_backend_webapi), or through a client library, such as [Steamworks.net](https://steamworks.github.io/).&#x20;
{% endhint %}

First let's look at the auth scheme to determine what Elements is expecting:

```json
{
            "id": "67d673f5131dde00b60e230a",
            "name": "Steam",
            "validationUrl": "https://api.steampowered.com/ISteamUserAuth/AuthenticateUserTicket/v1/",
            "headers": [
                {
                    "key": "x-webapi-key",
                    "value": "Copy from Steam publishing settings.",
                    "fromClient": false
                },
                {
                    "key": "Content-Type",
                    "value": "application/x-www-form-urlencoded",
                    "fromClient": false
                }
            ],
            "params": [
                {
                    "key": "appid",
                    "value": "Steam AppId",
                    "fromClient": false
                },
                {
                    "key": "ticket",
                    "value": "Ticket from GetAuthSessionTicket (Sent from frontend)",
                    "fromClient": true
                },
                {
                    "key": "identity",
                    "value": "You define this when requesting the ticket. Must match frontend.",
                    "fromClient": false
                }
            ],
            "responseIdMapping": "steamid"
        }
```

We're basically telling it how to format the request that Elements will send to the authenticating server. In this case, we're telling Elements to expect the ticket to be sent from the client (the only header or parameter with `fromClient` as true), and that all other values will be preset in the scheme and stored within Elements.&#x20;

{% hint style="info" %}
When you make the call to GetAuthTicketForWebApi to retrieve the auth ticket, you pass in an identity value. This can be anything (or nothing), but must match on the client and server side.
{% endhint %}

When we make a request against the [/auth/oauth2](https://manual.namazustudios.com/v3/restful-apis/api-specification/auth_scheme/oauth2) endpoint, Elements will format a new request using the `headers` and `params` information in the scheme, and will send the request to the `validationUrl`  defined in the scheme. In this case, we only told the scheme to expect one parameter, `"ticket"`, and no headers from the client, so our request would look like this:

```json
Example: 
POST http://localhost:8080/api/rest/auth/oauth2

Body:
{
    "schemeId":"Steam",
    "requestParameters" : {
        "ticket":"<Your Steam ticket from GetAuthTicketForWebApi call. Will be very long, around 5120 characters.>""
    }
}

```

When Elements receives the response, it will use the `responseIdMapping` to look for a corresponding key, and will assume the value of this key is the user's id.&#x20;

```json
Example response from Steam (handled internally in Elements):
{
    "response": {
        "params": {
            "result": "OK",
            "steamid": "<steam user id>",
            "ownersteamid": "<steam user id>",
            "vacbanned": false,
            "publisherbanned": false
        }
    }
}
```

If Elements retrieves the user id successfully, it will automatically associate this Steam user id with an Elements user, and return the [Elements Session](https://manual.namazustudios.com/v3/core-features/sessions) object back to you.

Once you have the Session object, just add the `sessionSecret` to the `Elements-SessionSecret` header for subsequent requests, and you're all set!