Last Updated: 10/27/2021, 8:09:47 AM

# IAM Clients

# Overview

An IAM client is defined as an application, such as a game server or website, that requests access to protected platform resources. IAM clients allow you to control which resources can be accessed by an application, as opposed to a specific user.

IAM clients implement the OAuth 2.0 specification. You may have used other OAuth clients in the past, such as when using your GMail or Facebook account to log in to websites.

IAM clients can be defined under the publisher or game namespace, depending on whether the intended application is specific to one of your games or used by all games on your platform.

# Client Types

There are two client types, per the OAuth 2.0 Client Type specification:

  • A confidential client requires a combination of Client ID and Client Secret to authorize with the backend. Confidential clients are normally needed in cases where you do not want to log in with a user account (such as a game server), and as a result, will typically have access permissions defined on the client itself. Therefore, confidential clients should only be used in cases where you can control who has access to the client’s ID and secret, to prevent unauthorized users from being able to access your services.
  • A public client does not specify a client secret; only the client ID is needed for authorization. Public clients are best for applications that require a user to log in with their user account. Permissions should generally not be defined for public clients, since the user’s permissions will override the client’s permissions once the user is signed into their account.

# Common IAM Clients

Most projects typically define a few common client archetypes:

  • Game client IAM client for game clients should be configured as public. It should have no permissions assigned, because the permissions will come from the signed-in user.
  • Game server hosted by Armada IAM client for dedicated servers should also be configured as public, but you will need to assign permissions to the client if your dedicated servers do not login as a user (the most common case). For an example of permissions that would typically be assigned to a dedicated server IAM client, see the example permissions below.
  • Dedicated Server Uploader IAM client for uploading dedicated server builds. Since access for uploaders is usually tightly controlled, it is best to specify these types of clients as confidential.
  • Launcher IAM clients for the launcher should be configured as a public client. Once the user signs in, that user’s permissions will override the launcher client permissions. But the launcher client will need to be given permissions to access certain services on its own, such as the login service.

# Fields

  • Client ID serves as the unique ID for the client across the system. It is automatically generated when you first create the client.

  • Client Type defines how secure the client’s login tokens will be. You can choose between Public and Confidential types. Refer to the Client Types section to read more about this.

  • Secret serves as the password for confidential clients. You can fill the field manually, or have the system create one for you by clicking the Generate Client Secret button.

    NOTE

    Once the client has been created, you can no longer access the client secret. Make sure you save the secret in a secure place.

  • Client Name serves as the name of the client, and is how this client will be identified in user-facing forms and documents.

  • Namespace defines which namespace this client should be created within. This only affects where the client appears in the Admin Portal, and does not necessarily affect what resources the client can access.

  • Base URI is only needed for clients that are used by services, and should be set to the URI of the service itself. For clients that are not intended to be used to allow a service to access the rest of the platform, the value should be empty.

  • Target Audience is used to constrain which service endpoints the client is allowed to access. When given a value, it serves as a white list to allow backend services to quickly reject connection attempts before client or user permissions are checked.
    When a client attempts to access a service endpoint, the service first checks the client’s Target Audience list. The connection attempt will be rejected if the service’s URI does not match the Base URI of any of the clients listed in the Target Audience field (unless the field is empty). If the client passes the Target Audience check (or if the client’s Target Audience field is empty), the service proceeds to the next step in authenticating the client’s request, such as checking permissions or scope. The Target Audience drop down contains a list of clients (from the namespace that the client is defined in) along with the Base URI value specified by that client.

  • Redirect URI is only used by clients that represent web-based applications (such as a website or a launcher). For web-based clients, the value should be set to the URL that the user should be redirected to upon successful login. For other types of clients (game server, game client, server uploaders, etc.), although the RedirectURI is not used for anything, it’s customary to put http://127.0.0.1, as this field must have a value for all clients.

# Prerequisites

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage IAM clients in the Admin Portal. For a full list of permissions that impact IAM management, see the IAM tab of the permissions reference.

Usage Permissions Action
Create a Client ADMIN:NAMESPACE:{namespace}:CLIENT Create
Retrieve Client ADMIN:NAMESPACE:{namespace}:CLIENT Update
Update Client ADMIN:NAMESPACE:{namespace}:CLIENT Update
Update Client Permission ADMIN:NAMESPACE:{namespace}:CLIENT Update
Add Client Permission ADMIN:NAMESPACE:{namespace}:CLIENT Update
Delete Client Permission ADMIN:NAMESPACE:{namespace}:CLIENT Update

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

# Managing Clients in the Admin Portal

# Create a Client

  1. In the Admin Portal, go to the Platform Configuration section and click the OAuth Clients menu.

    iam-clients

  2. On the OAuth Clients page, make sure that you are in the right namespace. Then, click Create New and fill out the appropriate fields (see the Fields section above for more information).

    iam-clients

  3. When you’re done, click Create. The new IAM Client will be created.

# Add Permissions to a Client

After you create a client, you can add permissions to the client by following the steps below.

  1. In the Admin Portal, go to the Platform Configuration section and click the OAuth Clients menu.

    iam-clients

  2. Click View next to the client you want to add permissions to.

    iam-clients

  3. On the Client Details page, switch to the Permissions tab.

    iam-clients

  4. Click the Add button to add a new permission to the client.

    iam-clients

  5. Fill in the required fields:

    • Enter a permission tag into the Resource field. A permission tag is a string containing multiple tokens that is used to grant access to specific resources. For more information, see the Permissions page or the permissions reference.
    • Select the action or actions the permission requires in the Action field. These are also listed in the permissions reference.

    iam-clients

    Here’s a list of permissions required or frequently used by each common client type:

# Dedicated Server Client - Mandatory

Permission Action
ADMIN:DSM READ
NAMESPACE:{namespace}:DSM:SERVER UPDATE

# Dedicated Server Client - Optional

You should give these permissions to a dedicated server client depending on the services you are using. See the permissions reference for more information about what these permissions do.

Permission Action
ADMIN:NAMESPACE:{namespace}:ENTITLEMENT READ
ADMIN:NAMESPACE:{namespace}:PARTY:STORAGE READ, UPDATE
ADMIN:NAMESPACE:{namespace}:STATITEM UPDATE
ADMIN:NAMESPACE:{namespace}:USER:*:ACHIEVEMENT UPDATE
ADMIN:NAMESPACE:{namespace}:USER:*:CLOUDSAVE:RECORD CREATE, READ, UPDATE, DELETE
ADMIN:NAMESPACE:{namespace}:USER:*:ENTITLEMENT READ
ADMIN:NAMESPACE:{namespace}:USER:*:PUBLIC:CLOUDSAVE:RECORD CREATE, READ, UPDATE
ADMIN:NAMESPACE:{namespace}:USER:*:STATITEM CREATE, READ, UPDATE
ADMIN:NAMESPACE:{namespace}:USER:*:WALLET UPDATE
NAMESPACE:{namespace}:SESSION CREATE, READ, UPDATE
ADMIN:NAMESPACE:{namespace}:MATCHMAKING:CHANNEL CREATE, DELETE

# Dedicated Server Uploader Client - Mandatory

Permission Action
NAMESPACE:{namespace}:DSM:SERVER Create, Update

When you’re done, the permission will appear in the client’s permission list.

iam-clients

# Managing Clients Using API

You can also use our API to manage clients. Here are a couple of endpoints that can help you when you’re creating or assigning permissions to a client.

# Create a Client

  1. Use the Create Client: POST - /iam/v3/admin/namespaces/{namespace}/clients endpoint.

  2. In the Namespace field, enter the namespace that the IAM Client will access resources from.

  3. Fill out the Request Body:

    • Enter a name for the client in the Client Name field, e.g. Game Client Test.
    • Fill in the Client Permissions. For more details, see the Permissions documentation.
    • In the Action field, enter the number that corresponds to the bitmask of actions that you want to grant to the IAM client:
    Action Number Description
    1 Create
    2 Read
    3 Create, Read
    4 Update
    5 Update, Create
    6 Update, Read
    7 Update, Read, Create
    8 Delete
    9 Delete, Create
    10 Delete, Read
    11 Delete, Read, Create
    12 Delete, Update
    13 Delete, Update, Create
    14 Delete, Update, Read
    15 Delete, Update, Read, Create
    • Enter the permission tag for any endpoint the client will need to access in the Resource field. See the permission reference for a full list.
    • The following parameters are optional, and can be used to schedule permissions that are granted on a temporary basis. If you want your new client to keep its permissions permanently, leave these fields blank.
    • Enter the desired action value into the SchedAction field.
    • For recurring permissions, enter the desired date range in UTC format into the SchedCron field.
    • Enter the start and end dates for the permission into the SchedRange field.
    • In the Namespace field, enter the namespace that the client should be created within.
    • Enter the appropriate client type into the oauthClientType field. See the Client Types and Common IAM Clients sections above to help determine which client type you should use.
    • Enter the redirection endpoint into the Redirect URI field.
    • If you are creating a confidential client, enter a password for the client into the Client Secret field.

    NOTE

    Once the client has been created, you can no longer access the client secret. Make sure you save the secret in a secure place.

Upon a successful request, the client will be created in the desired namespace. Here is an example of a response to a successful request:

# Add Permissions to a Client

  1. Use the Add Client Permissions: POST - /iam/v3/admin/namespaces/{namespace}/clients/{clientId}/permissions endpoint.

  2. Enter the namespace where the client was created into the Namespace field.

  3. Enter the client’s ID into the Client ID field.

  4. Fill out the request body:

    • In the Action field, enter the number that corresponds to the bitmask of actions that you want to grant to the IAM client:
    Action Number Description
    1 Create
    2 Read
    3 Create, Read
    4 Update
    5 Update, Create
    6 Update, Read
    7 Update, Read, Create
    8 Delete
    9 Delete, Create
    10 Delete, Read
    11 Delete, Read, Create
    12 Delete, Update
    13 Delete, Update, Create
    14 Delete, Update, Read
    15 Delete, Update, Read, Create
    • Enter the permission tag for any endpoint the client will need to access in the Resource field. See the permission reference for a full list.

Upon a successful request, the permissions you defined will be assigned to the client. A successful request returns Code 204 No Content, which indicates that the request was successful.

  • Permissions are used to grant clients access to resources.