Authentication providers

Authentication providers let you plug any identity system into Nakama as a first-class sign-in method. In addition to the social providers Nakama supports natively, you can connect a third-party identity provider or your own. You can also import the player’s friends from that platform into Nakama’s friend graph.

The provider module #

A provider module is server runtime code that sits between Nakama and an external identity platform. Nakama provides the client API endpoints, keeps track of the providers you register, and links identities to accounts. The module implementation is custom per platform.

You can write your own module with the server runtime API. Our goal is to have a range of provider modules for social platforms published as open-source plugins.

How a provider identity sits on a Nakama account #

A provider identity is a first-class identifier. It can create or sign into a Nakama account using a third-party platform’s user ID. A Nakama account holds one identity per registered provider alongside its device IDs, email and social IDs, as described in how accounts and identifiers relate.

Provider identity #

An authentication provider for an external platform is identified by the combination of provider name and provider user ID. For example:

1
2

  provider name:    epic
  provider user ID: 123456789

• The provider name: The name can contain letters, numbers, underscores, and hyphens ([a-zA-Z0-9_-]), up to 128 bytes. Nakama lowercases the provider name at registration and when handling authenticate and link requests, so Epic, EPIC, and epic all resolve to the same provider. The lowercase form is stored with the provider identity and shown in the Nakama Console.
• The provider user ID: There is no required format for the provider ID. It can be whatever immutable account ID the external platform uses. The only requirement is that the ID cannot contain whitespace or control characters. The maximum allowed length is 128 bytes.

As with the built-in social IDs, these same two rules apply to a provider identity:

• An account can hold only one identity per provider. For example, a second epic identity cannot be added to an account that already has one.
• A provider identity can belong to only one account. For instance, the same epic ID cannot sign a player into two accounts.

Authentication flow #

The client sends Nakama a provider name and an opaque payload. Nakama passes the payload to your provider module, which verifies the credential with the external platform and returns the player’s stable provider account ID.

The sequence is:

1. The client sends a provider name and payload to Nakama. The payload is opaque JSON. See Define your payload
2. Nakama passes the payload to your provider module.
3. Your provider verifies the credential. The provider communicates with the external platform and verifies that the credential belongs to a valid account.
4. Your provider returns the platform account ID.
5. Nakama maps the provider identity to a Nakama account. If the identity is new and create is true, Nakama creates an account. Otherwise, Nakama returns the existing account.
6. If your provider implements friends import, Nakama calls it and your provider returns the player’s friends list, which Nakama adds to the new or existing account’s friend graph.
7. The client receives a Nakama session.

Importing friends #

When the external platform exposes the player’s social graph, your provider can import those friends into Nakama during the same authenticate or link request. If you implement the GetFriends runtime function, Nakama makes a separate call to it right after Authenticate returns, passing it the authenticate result.

After your provider returns the player’s friends from the external platform, Nakama matches them against existing Nakama accounts that use the same provider identity, adding each match to the player’s friend graph. Friends without a Nakama account are skipped. For implementation details, see Import friends from the provider.

Creating a provider #

To create a provider, implement a function that verifies the player’s credential with the external platform and returns the player’s provider user ID. Then register the function with Nakama using the server runtime API.

Here are the steps:

1. Choose the provider name #

• Pick the name clients will send, such as epic. See provider identity for the naming rules and how casing is handled.
• Once you use a name for an identity system, you can’t change it. Renaming a provider after launch breaks the link between that provider and the accounts that use it.

2. Define your payload #

• The payload is JSON. The client sends a JSON object, Nakama parses it, and passes it to your function without inspecting the contents.
• The shape is whatever your provider needs: a single access token, an authorization code, a signed ticket, or several values together.

3. Write the authenticate function #

This is the function Nakama calls for every authenticate and link request for your provider. It receives the payload from the client, verifies the credential, and returns the player’s provider user ID.

In Go, a provider satisfies the following interface:

1
2
3
4

type AuthenticateProvider interface {
    Authenticate(ctx context.Context, logger Logger, db *sql.DB, nk NakamaModule, payload map[string]any) (AuthenticateProviderResult, error)
    GetFriends(ctx context.Context, logger Logger, db *sql.DB, nk NakamaModule, payload map[string]any, result AuthenticateProviderResult) ([]string, bool, error)
}

Authenticate verifies the credential. GetFriends imports the player’s friends from the external platform and is covered in step 4. If you don’t need the friends import functionality, you can implement GetFriends to return nil.

What to return #

Your function returns the provider user ID, and optionally a username, session variables, and metadata.

1
2
3
4
5
6

type DefaultAuthenticateProviderResult struct {
    ProviderUserID string            `json:"provider_user_id"`
    Username       string            `json:"username,omitempty"`
    Vars           map[string]string `json:"vars,omitempty"`
    Metadata       map[string]any    `json:"metadata,omitempty"`
}

• Provider user ID, required. The value Nakama stores and looks up on every subsequent sign-in. See provider identity for the rules it must satisfy.
• Username, optional. Used only when creating an account.
• Session variables, optional. String values only, bundled into the session token.
• Metadata, optional. This is used as a bridge from Authenticate to GetFriends. GetFriends is the runtime function that gets called after authentication succeeds. Often some kind of token information is needed to perform a friends request; this metadata field can keep that token so friends request can read it. See step 4.

Here’s an example in Go:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

type EpicProvider struct{}

func (p *EpicProvider) Authenticate(ctx context.Context, logger runtime.Logger,
    db *sql.DB, nk runtime.NakamaModule, payload map[string]any) (runtime.AuthenticateProviderResult, error) {

    accessToken, _ := payload["access_token"].(string)
    if accessToken == "" {
        return nil, runtime.NewError("payload is missing access_token", 3)
    }

    // Verify the token with Epic and read back the account it belongs to.
    // Replace this with a real call to the platform's API.
    account, err := verifyWithEpic(ctx, accessToken)
    if err != nil {
        return nil, runtime.NewError("token rejected by provider", 16)
    }

    return &runtime.DefaultAuthenticateProviderResult{
        ProviderUserID: account.ID,
        Vars:           map[string]string{"platform": "epic"},
        // Set it here so GetFriends can read it.
        Metadata:       map[string]any{"access_token": accessToken},
    }, nil
}

4. Import friends from the provider #

During authentication and linking, if the external platform exposes the player’s friends, your provider can import them into Nakama’s friend graph.

This is done by implement GetFriends runtime function. Here’s the shape:

1
2
3
4

type AuthenticateProvider interface {
    Authenticate(ctx context.Context, logger Logger, db *sql.DB, nk NakamaModule, payload map[string]any) (AuthenticateProviderResult, error)
    GetFriends(ctx context.Context, logger Logger, db *sql.DB, nk NakamaModule, payload map[string]any, result AuthenticateProviderResult) ([]string, bool, error)
}

Nakama calls GetFriends right after Authenticate and passes the result you returned. This is where the Metadata field mentioned in step 3 comes in. Authenticate can hand data to GetFriends through the result’s Metadata field, such as an access token it obtained while verifying the credential.

In addition to the friends’ provider user IDs, your function call can do a reset of the player’s friends. Set the boolean in the return value to true to replace the existing friends, false to add to them.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

func (p *EpicProvider) GetFriends(ctx context.Context, logger runtime.Logger,
    db *sql.DB, nk runtime.NakamaModule, payload map[string]any,
    result runtime.AuthenticateProviderResult) ([]string, bool, error) {

    // Read the token Authenticate stored in the result metadata.
    accessToken, _ := result.GetMetadata()["access_token"].(string)

    friendIDs, err := listEpicFriends(ctx, accessToken)
    if err != nil {
        return nil, false, err
    }

    return friendIDs, false, nil
}

5. Register the provider #

Register your provider during runtime initialization. In Go, use RegisterAuthenticateProvider to register the provider with Nakama.

1

RegisterAuthenticateProvider(name string, provider AuthenticateProvider) error

The provider argument is the type whose authenticate function you wrote in step 3.

Here’s an example:

1
2
3
4

func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB,
    nk runtime.NakamaModule, initializer runtime.Initializer) error {
    return initializer.RegisterAuthenticateProvider("epic", &EpicProvider{})
}

Linking and unlinking #

As with Nakama’s native social sign-in methods, you can link a provider identity to an existing Nakama account. Use authenticate to find or create an account from a provider identity, and link to add that identity to an account the player is already signed in to.

There are two ways to use a provider identity:

• Authenticate first, link later. The player signs in with a device ID, email, or social ID, then links the provider identity to their existing account.
• Authenticate with the provider first. A provider identity can be used to create a Nakama account just like any other identity. You can then link other sign-in methods to the account.

To use the link functionality, you must register the provider’s Authenticate runtime function first. Nakama passes the client payload to the registered function to verify the credential and obtain the provider user ID.

Unlinking removes the provider identity from the account. The last remaining identifier cannot be unlinked, so the player always has a way to sign in.

Hooks #

Just like the built-in authentication methods, you can run custom logic around each provider operation with before and after hooks. See Hooks.

Related Pages

• Authentication
• Session
• Server Framework Introduction
• Go Runtime