Last modified November 29, 2024

Additional details on authentication for the platform API

Details of the id token

Regardless of which login method is used, once this is done, the user’s client (web UI, kubectl etc.) will send an ID token with every request to the platform API. The ID token contains information about the user which can then be used in authorization to decide which permissions the user should be granted.

The ID token is a JSON Web Token (JWT). The payload part of an ID token issued for the platform API can look like in the following example. Note that we omit some parts that aren’t relevant for the purpose of this article.

{
  "iss": "https://dex.g8s.garlic.eu-west-1.aws.gigantic.io",
  "exp": 1645533923,
  "iat": 1645532123,
  "email": "jane@example.com",
  "groups": [
    "customer:GiantSwarmAdmins"
  ],
  "name": "Jane Smith",
  "preferred_username": "janes",
  ...
}

Let’s go into details for the most relevant properties (also called “claims”) of this payload object.

Token lifetime

By default, ID tokens for the platform API are issued with a lifetime of 30 minutes.

After that period, clients like kubectl will automatically attempt to get a fresh token from the identity provider. This doesn’t require any additional user interaction. However, when this happens, the round-trip time for a kubectl command can be increased by a few seconds.

It’s possible to configure a shorter token lifetime at the cost of more frequent delays due to token refreshing. Please contact your account engineer for assistance.

When assigning users to groups in your identity provider, and when removing users from groups, it can take up to 30 minutes until the change becomes effective for end users. If a user has authenticated and obtained an ID token before the change, tools like kubectl will use that token until it expires.

Single sign-on requirements

Giant Swarm assists all customers with setting up single sign-on (SSO) for the platform API. During that process, we make sure that these requirements are met:

• As a customer, you need to decide on an identity provider to use. Most enterprise-grade organizations have a solution already in place. Since we use Dex as a connector between the platform API and your identity provider, we can support a variety of common standards like OpenID Connect (OIDC) and LDAP.

  For cases where no suitable identity provider is available, or not yet available, we recommend to use GitHub, where an organization and teams can be set up and managed easily.

• Your identity provider must define a group to be considered as admins for the Giant Swarm installation. All members of this group automatically get administrative permissions when authenticating with the platform API.

Further reading

• Authentication for programmatic access explains how to authenticate in an automation context
• Authorization in the platform API explains how to assign permissions to authenticated users