From 7b4eb906bdcb3d8c68e42fae5ef8af4e1e8d27c4 Mon Sep 17 00:00:00 2001 From: "David B. Maier" Date: Sat, 28 Dec 2024 16:07:38 +0100 Subject: [PATCH] Restructure auth documentation --- docs/auth.md | 154 --------------------------------------------- docs/auth/dedi.md | 49 +++++++++++++++ docs/auth/index.md | 24 +++++++ docs/auth/token.md | 106 +++++++++++++++++++++++++++++++ docs/auth/ubi.md | 87 +++++++++++++++++++++++++ docs/index.md | 3 +- 6 files changed, 268 insertions(+), 155 deletions(-) delete mode 100644 docs/auth.md create mode 100644 docs/auth/dedi.md create mode 100644 docs/auth/index.md create mode 100644 docs/auth/token.md create mode 100644 docs/auth/ubi.md diff --git a/docs/auth.md b/docs/auth.md deleted file mode 100644 index abdd4de..0000000 --- a/docs/auth.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -icon: "fa-lock" ---- - -# Authentication - -This guide will explain how to authenticate with Nadeo's API. There are 2 methods of doing so, one is via a Ubisoft account, and one is via a dedicated server account. Note that the dedicated server account way is easier but imposes **some** limitations on what you can access with the API, but it could be enough. - -Refer to Miss' [Nadeo Go package](https://github.com/codecat/gonadeo) for a complete example. - -## With a Ubisoft account - -Send a POST request to the following URL: - -```plain -https://public-ubiservices.ubi.com/v3/profiles/sessions -``` - -With the following request headers: - -```plain -Content-Type: application/json -Ubi-AppId: 86263886-327a-4328-ac69-527f0d20a237 -Authorization: Basic -``` - -Where the `Authorization` header is a basic authorization of your Ubisoft email and password (e.g. `email@address.com:password` becomes `Basic ZW1haWxAYWRkcmVzcy5jb206cGFzc3dvcmQ=`). -In Go for example, this is done via [SetBasicAuth](https://pkg.go.dev/net/http#Request.SetBasicAuth). - -Also, make sure you pass a valid user agent that Ubisoft can understand. Ubisoft blocks certain default user agents, so make sure you pass your own. Include your project name and a way to contact you. (This counts not only for the Ubisoft API, but also Nadeo's API.) For example: - -```plain -User-Agent: My amazing app / my.email.address@example.com -``` - -The response will contain a Ubisoft authentication ticket that you can use for Nadeo's Ubiservices authentication endpoint. Next, send a POST request to the following URL: - -```plain -https://prod.trackmania.core.nadeo.online/v2/authentication/token/ubiservices -``` - -With the following request headers: - -```plain -Content-Type: application/json -Authorization: ubi_v1 t= -``` - -Where `Authorization` has your Ubisoft account ticket right after `t=`. - -You also have to provide a request body, which is described below in the [Authorization section](#authorization). - -## With a dedicated server account - -If you don't want to or can't use a Ubisoft account for authentication, you can use a [dedicated server account](https://www.trackmania.com/player/dedicated-servers). Note that there are some limitations on what you can do with dedicated server tokens. - -Send a POST request to the following URL: - -```plain -https://prod.trackmania.core.nadeo.online/v2/authentication/token/basic -``` - -With the following request headers: - -```plain -Content-Type: application/json -Authorization: Basic -``` - -Where the `Authorization` header is a basic authorization of your dedicated server account (e.g. `username:password` becomes `Basic dXNlcm5hbWU6cGFzc3dvcmQ=`). -In Go for example, this is done via [SetBasicAuth](https://pkg.go.dev/net/http#Request.SetBasicAuth). - -You also have to provide a request body, which is described below in the [Authorization section](#authorization). - -# Authorization - -For both authentication methods described above, you have to provide a body telling the API what to authenticate with. The body of the request must be a Json object with the desired audience name: - -```json -{ "audience": "NadeoLiveServices" } -``` - -See a mapping of APIs and available audiences [here](#base-urls-and-audiences). -Note that if you don't provide a json body, you get a token for the audience `NadeoServices`. - -This will give you a [JSON web token](https://en.wikipedia.org/wiki/JSON_Web_Token) together with a refresh token: - -```json -{ - "accessToken": "eyJhbGciOiJIUzI1NiIsImVudiI6InRyYWNrbWFuaWEtcHJvZCIsInZlciI6IjEifQ..", - "refreshToken": "eyJhbGciOiJIUzI1NiIsImVudiI6InRyYWNrbWFuaWEtcHJvZCIsInZlciI6IjEifQ.." -} -``` - -If you URL-base64-decode the payload, you get the following json object: - -```json -{ - "jti": "", - "iss": "NadeoServices", - "iat": 1595191016, - "rat": 1595192816, - "exp": 1595194616, - "aud": "NadeoLiveServices", - "usg": "Server", - "sid": "", - "sat": 1595191016, - "sub": "", - "aun": "mm", - "rtk": false, - "pce": false, - "ubiservices_uid": "" -} -``` - -Where `exp` defines the expiration time, and `rat` the time after which you are able to refresh the token. - -## Token refreshing - -To refresh your token, send a POST to the following URL: - -```plain -https://prod.trackmania.core.nadeo.online/v2/authentication/token/refresh -``` - -With the `Authorization` header set to `nadeo_v1 t=`. - -The response is the same as with normal authentication. - -## Using the token - -All game APIs require you to send the obtained token along - the format is always the same. - -Simply set the following header on all your requests: - -```plain -Authorization: nadeo_v1 t= -``` - -And make sure you're using the correct audience for the endpoint (see the table below). - -## Making requests from Openplanet - -If you need to make requests to APIs from an Openplanet plugin, you don't need to do any authentication yourself. Use the [NadeoServices dependency](https://openplanet.dev/docs/reference/nadeoservices). - -# Base URLs and audiences - -The API base URLs and their necessary audiences are: - -| URL | Audience | -| -------------------------------------------- | ----------------- | -| https://prod.trackmania.core.nadeo.online/ | NadeoServices | -| https://live-services.trackmania.nadeo.live/ | NadeoLiveServices | -| https://meet.trackmania.nadeo.club | NadeoLiveServices | diff --git a/docs/auth/dedi.md b/docs/auth/dedi.md new file mode 100644 index 0000000..cdab596 --- /dev/null +++ b/docs/auth/dedi.md @@ -0,0 +1,49 @@ +--- +position: 1 +--- +# Dedicated server account + +If you don't want to or can't use a Ubisoft account for authentication, you can use a [dedicated server account](https://www.trackmania.com/player/dedicated-servers). Note that there are some limitations on what you can do with dedicated server tokens (as noted on relevant API endpoint documentation pages). + +## Setting up a dedicated server account + +A dedicated server account is always bound to a Ubisoft account. Visit [Trackmania.com's dedicated servers page](https://www.trackmania.com/player/dedicated-servers) to create a dedicated server account. + +Make sure to store the password after creating your account as it can't be retrieved again later. + +Note that your dedicated server account is directly associated to a Ubisoft account - if Nadeo/Ubisoft detect API usage they deem unacceptable, restrictions or bans on your dedicated server account may also have consequences for your associated Ubisoft account. + +## Acquiring a Nadeo API access token + +Send the following HTTP request using a tool/library of your choice: + +```plain +POST https://prod.trackmania.core.nadeo.online/v2/authentication/token/basic + +Headers: + Content-Type: application/json + Authorization: Basic + User-Agent: + +Body: + { "audience": "NadeoLiveServices" } +``` + +The `Authorization` header uses [Basic HTTP authentication](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side) for your dedicated server account credentials (e.g. `username:password` becomes `Basic dXNlcm5hbWU6cGFzc3dvcmQ=`). +In Go for example, this is done via [SetBasicAuth](https://pkg.go.dev/net/http#Request.SetBasicAuth) - other languages and libraries have their own utility methods for the same purpose. + +The body of the request must be a JSON object with the desired audience name. The audience(s) you need depend on the APIs and endpoints you intend to interact with. + +| URL | Audience | +| -------------------------------------------- | ----------------- | +| | NadeoServices | +| | NadeoLiveServices | +| | NadeoLiveServices | + +Note that if you don't provide a body, you get a token for the audience `NadeoServices`. + +If you plan to interact with API endpoints that require different audiences, you need to request multiple tokens and manage them separately. + +## Next steps + +The response body contains an `access_token` and a `refresh_token` which you can use for your API requests. See the [token usage guide](/auth/token) for information on how to use and manage tokens. diff --git a/docs/auth/index.md b/docs/auth/index.md new file mode 100644 index 0000000..263ffb0 --- /dev/null +++ b/docs/auth/index.md @@ -0,0 +1,24 @@ +--- +name: Authentication +pages: + - ubi + - dedi + - token +--- + +# Authentication + +This guide explains how to authenticate with Nadeo's APIs. There are 2 available methods: + +- [via a dedicated server account](/auth/dedi) +- [via a Ubisoft account](/auth/ubi) + +Dedicated server account authentication is easier to implement but imposes some limitations on what you can access with the API. The relevant restrictions are documented on each of the endpoint documentation pages. + +Both authentication paths result in one or more access tokens - see the [token usage guide](/auth/token) for information on how to use and manage them. + +For a complete authentication implementation example, you can refer to [Miss' Nadeo Go package](https://github.com/codecat/gonadeo). + +## Authentication in Openplanet + +If you need to make requests to Nadeo API endpoints from inside an Openplanet plugin, don't handle any of the authentication logic yourself. Instead, use the [NadeoServices dependency](https://openplanet.dev/docs/reference/nadeoservices) as a central authentication plugin. diff --git a/docs/auth/token.md b/docs/auth/token.md new file mode 100644 index 0000000..52320c1 --- /dev/null +++ b/docs/auth/token.md @@ -0,0 +1,106 @@ +--- +position: 3 +--- + +# Using API tokens + +This guide explains how to use and manage Nadeo API tokens. See the [authentication overview page](/auth) for information on how to acquire tokens. + +If you have already obtained an access token and want to get started, see the [basic usage guide](#using-the-access-token). + +To learn how to refresh your tokens without re-authenticating using a Ubisoft account of a dedicated server account, read the [section on refreshing your tokens](#refreshing-your-tokens). + +For more detailed information on the tokens' purposes and contents, refer to the [explanations below](#understanding-the-tokens). + +## Using the access token + +All game APIs require you to send the obtained access token along - the format is always the same. + +Simply set the following header on all your requests: + +```plain +Authorization: nadeo_v1 t= +``` + +## Refreshing your tokens + +To refresh your tokens (i.e. to obtain a new set of tokens without going through the entire authentication process), send the following HTTP request using a tool/library of your choice: + +```plain +https://prod.trackmania.core.nadeo.online/v2/authentication/token/refresh + +Headers: + Authorization: nadeo_v1 t= +``` + +The response contains new access and refresh tokens. + +## Understanding the tokens + +There are two types of tokens used by the Nadeo APIs: Access and refresh tokens. + +Both are sensitive credentials that can be used maliciously if you share them publicly, so treat them accordingly. + +### Access tokens + +Access tokens are used in every API request to identify yourself and prove that you are authorized to access that resource. + +They are signed [JSON web tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) that you can decode to understand and evaluate their contents (either programmatically or via a client-side decoder such as [JWT.io](https://jwt.io/)). + +An access token is always associated with a specific audience (as explained in the authentication methods' documentation pages) which is stored in the token's `aud` payload field. + +Access tokens are typically valid for one hour, which you can also verify via the token's `exp` payload field. + +See below for the available payload data in a typical access token (using a Ubisoft account access token as an example): + +```json +{ + "jti": "", // token ID + "iss": "NadeoServices", // issuer: always "NadeoServices" + "iat": 1735394983, // timestamp of issuance + "rat": 1735396783, // timestamp of when the token may be refreshed + "exp": 1735398583, // timestamp of expiry + "aud": "NadeoLiveServices", // audience: either "NadeoServices" or "NadeoLiveServices" + "usg": "Client", // usage: either "Client" for a Ubisoft account or "Server" for a dedicated server account + "sid": "", // session ID + "sat": 1735394983, // timestamp of signing, typically equal to "iat" + "sub": "5b4d42f4-c2de-407d-b367-cbff3fe817bc", // subject: Nadeo account ID of the authenticated user + "aun": "tooInfinite", // display name of the user/dedicated server account + "rtk": false, // flag to indicate refresh tokens, always false for access tokens + "pce": false, // always false + "ubiservices_uid": "a59df3e8-6bff-48a2-98b6-801abf2a298e" // Ubisoft account ID, also known as web identity +} +``` + +### Refresh tokens + +Refresh tokens are used to acquire a new set of tokens without going through the entire authentication procedure required for the initial tokens. + +They are signed [JSON web tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) that you can decode to understand and evaluate their contents (either programmatically or via a client-side decoder such as [JWT.io](https://jwt.io/)). + +A refresh token is always associated with an access token, and using it will yield another access token of the same audience. + +Refresh tokens are typically valid for one day, which you can also verify via the token's `exp` payload field. + +See below for the available payload data in a typical refresh token (using a Ubisoft account access token as an example): + +```json +{ + "jti": "", // token ID + "iss": "NadeoServices", // issuer: always "NadeoServices" + "iat": 1735394983, // timestamp of issuance + "rat": 1735438183, // timestamp of when the token may be refreshed, not used for refresh tokens + "exp": 1735481383, // timestamp of expiry + "aud": "NadeoServices", // audience: always "NadeoServices", not to be confused with "refresh_aud" + "usg": "Client", // usage: either "Client" for a Ubisoft account or "Server" for a dedicated server account + "sid": "", // session ID + "sat": 1735394983, // timestamp of signing, typically equal to "iat" + "sub": "5b4d42f4-c2de-407d-b367-cbff3fe817bc", // subject: Nadeo account ID of the authenticated user + "aun": "tooInfinite", // display name of the user/dedicated server account + "rtk": true, // flag to indicate refresh tokens, always true for refresh tokens + "pce": false, // always false + "ubiservices_uid": "a59df3e8-6bff-48a2-98b6-801abf2a298e", // Ubisoft account ID, also known as web identity + "refresh_aud": "NadeoLiveServices", // refresh audience, audience for tokens refreshed with this refresh token + "limit_type": "none" // always "none" +} +``` diff --git a/docs/auth/ubi.md b/docs/auth/ubi.md new file mode 100644 index 0000000..1d28b9e --- /dev/null +++ b/docs/auth/ubi.md @@ -0,0 +1,87 @@ +--- +position: 2 +--- + +# Ubisoft account + +Using a Ubisoft account for authentication lets you access all API endpoints as a real user. This process mimicks the game's authentication procedure. + +## Setting up a Ubisoft account + +It's recommended not to use your primary account for API access. Temporary or permanent restrictions or bans will affect your ability to play the game, so it's recommended to create a separate Ubisoft account for these use cases. + +Note that this does not protect you from IP bans or similar restrictions (so this is obviously not a carte blanche for irresponsable API usage), but it can prevent accidental rate limit violations from affecting your primary Ubisoft account. + +You can create a new account via the [Ubisoft website](https://www.ubisoft.com). + +## Authentication process + +The Ubisoft account authentication process requires you to send two separate requests. + +- The first request authenticates your Ubisoft account with Ubisoft's account management API, which results in an authentication `ticket`. +- Using that `ticket`, the second request authenticates your account with Nadeo's account management API, giving you an access token. + +### Acquiring a Ubisoft ticket + +Send the following HTTP request using a tool/library of your choice: + +```plain +POST https://public-ubiservices.ubi.com/v3/profiles/sessions + +Headers: + Content-Type: application/json + Ubi-AppId: 86263886-327a-4328-ac69-527f0d20a237 + Authorization: Basic + User-Agent: +``` + +The `Ubi-AppId` header is a fixed value and should not be changed. + +The `Authorization` header uses [Basic HTTP authentication](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side) for your dedicated server account credentials (e.g. `username:password` becomes `Basic dXNlcm5hbWU6cGFzc3dvcmQ=`). +In Go for example, this is done via [SetBasicAuth](https://pkg.go.dev/net/http#Request.SetBasicAuth) - other languages and libraries have their own utility methods for the same purpose. + +Ubisoft blocks certain default user agents, so make sure you pass your own that includes your project name and a way to contact you. This is a good practice for all Ubisoft and Nadeo API endpoints you interact with. + +The response contains a Ubisoft authentication `ticket` that you can use for authenticating with Nadeo's APIs as documented below. + +#### Common issues + +- I'm getting error responses with status code `429`. + +Ubisoft's API imposes a rate limit on their authentication endpoints, and sending requests too frequently may get you temporarily restricted. This typically lasts up to an hour and cannot be circumvented. + +- I'm getting error responses with status code `403` and error code `4000`. + +Ubisoft's API blocks certain user agents (e.g. the default user agent set by the `requests` Python library). Make sure you're using a custom `User-Agent` header. + +### Acquiring a Nadeo API access token + +Send the following HTTP request using a tool/library of your choice: + +```plain +https://prod.trackmania.core.nadeo.online/v2/authentication/token/ubiservices + +Headers: + Content-Type: application/json + Authorization: ubi_v1 t= + User-Agent: + +Body: + { "audience": "NadeoLiveServices" } +``` + +The body of the request must be a JSON object with the desired audience name. The audience(s) you need depend on the APIs and endpoints you intend to interact with. + +| URL | Audience | +| -------------------------------------------- | ----------------- | +| | NadeoServices | +| | NadeoLiveServices | +| | NadeoLiveServices | + +Note that if you don't provide a body, you get a token for the audience `NadeoServices`. + +If you plan to interact with API endpoints that require different audiences, you need to request multiple tokens and manage them separately. + +## Next steps + +The final response body contains an `access_token` and a `refresh_token` which you can use for your API requests. See the [token usage guide](/auth/token) for information on how to use and manage tokens. diff --git a/docs/index.md b/docs/index.md index cd33028..449793c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,13 +1,14 @@ --- pages: - - auth - glossary dirs: + - auth - core - live - meet roots: - oauth + --- # Home