OAuth2

When creating a new Session, you have the option to authenticate using a predefined OAuth2 Auth Scheme.

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

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.

It will be necessary to have a registered application on Steam, as this process will require an application id.

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.

This assumes that you already have a process set up to retrieve the auth ticket, either manually as depicted in the Steam documentation, or through a client library, such as Steamworks.net.

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

{
            "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.

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.

When we make a request against the /auth/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:

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.

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 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!