Personal Access Tokens

Personal Access Tokens (PATs) are JSON Web Tokens (JWT) that can be used as bearer tokens to authenticate API requests made to EAS and EWB. EAS can generate two types of Access Tokens, User Tokens and Machine Tokens.

User Tokens

info

User tokens expire after 30 Days.

User tokens are intended for use by individual users. All users can generate Personal Access Tokens with a subset of their External Roles via the https://<EAS_DOMAIN>/profile/user-tokens page in the EAS web app. These tokens are associated with the user that originally created them and all requests made with these tokens are made on behalf of that user. There is no limit to the number of tokens a user can generate.

Machine Tokens

danger

Machine tokens do not expire and cannot be individually revoked.

Machine tokens are intended for long-running or shared services that need to connect to EAS or EWB. Machine tokens can only be created by an administrator with the SUPER_ADMIN or INTEGRATION_ADMIN roles via the https://<EAS_DOMAIN>/admin/machine-tokens page in the EAS web app.

Machine tokens can be created with any combination of External Roles regardless of the roles of the administrator creating them.

Machine tokens are not associated with any existing user, instead a new EAS "Machine Token User" is created for each machine token. Requests performed using these tokens are made on behalf of its associated "Machine Token User". A full list of "Machine Token Users" can be found via the https://<EAS_DOMAIN>/admin/machine-tokens page.

EAS Configuration

info

Personal Access Tokens can be configured in combination with both Auth0 and EntraID.

To enable the use of Personal Access Tokens with EAS, the following configuration is required to be updated.

jwks.issuer: This will be used to populate the Issuer ("iss") claim in the generated tokens. This should be the URL of the EAS server.

note

Any services configured to trust tokens generated by EAS will also need to be able to make requests to <jwks.issuer>/.well-known/openid-configuration and <jwks.issuer>/.well-known/jwks to verify EAS generated tokens.

auth.trustedIssuers: By default, EAS will not accept tokens it generates. The URL of the EAS server must be added to its list of trustedIssuers just like any other token issuer. This value should match the value set in jwks.issuer.

note

Any other service such as EWB that need to accept tokens generated by EAS, also need to have the URL of the EAS server added to their list of trustedIssuers.

Example configuration:

{
    "jwks": {
        "issuer": "https://dev-env.example.com:7654"
    },
   "auth": {
      "method": "entraid",
      "trustedIssuers": [
        "https://login.microsoftonline.com/ee3c421e-56c1-452d-a371-5cd884fd7ca7/v2.0",
        "https://dev-env.example.com:7654"
      ],
      "audience": "d92a9e09-258c-4e53-8b16-5a5b9e02404c"
   }
}

Full configuration details can be found here.

Signing Keys

The signing keys for EAS tokens are generated by EAS and stored in its database. On startup if the EAS database does not contain a key with the name configured in jwks.currentUserSigningKey or jwks.currentMachineSigningKey it will generate and store a new key with that name on first use.

EAS will provide the public keys for all(previous and current) signing keys found in its database at the JWKS endpoint <EAS_DOMAIN>/.well-known/jwks.

Creating Tokens with GraphQL

Personal Access Tokens can also be generated via the EAS GraphQL API. The GraphQL API is served at /api/graphql

User Token

query {
    createUserApiKey(
        roles: ["MODELLER"],
        tokenName: "model_exporter_token"
    )
}

Machine Token

query {
    createMachineApiKey(
        roles: ["EWB_ADMIN", "MAP_VIEWER"],
        tokenName: "ewb_controller"
    )
}

Using EAS Access Tokens With The EWB SDK

To allow the use of EAS generated tokens with the EWB SDK, the following EAS permissions are mapped to the three roles defined by the EWB.

EAS Permission	EWB Role	EWB access provided	Provided by default "External Role"
EWB:READ	read:ewb	Access to connect to the network service with a gRPC NetworkConsumerClient. Also to all EWB HTTP REST endpoints (excluding /ewb/api/graphql/customers).	SUPER_ADMIN, MAP_VIEWER
EWB:UPDATE	write:ewb	Access to connect to the network service with a gRPC UpdateNetworkStateClient.	SUPER_ADMIN, EWB_UPDATER
EWB_CUSTOMER:READ	read:customer	Access to connect to the customer service with a gRPC CustomerConsumerClient. Also to the customer GraphQL endpoint /ewb/api/graphql/customers.	SUPER_ADMIN, EWB_CUSTOMER_VIEWER
EWB_DIAGRAM:READ	read:diagram	Access to connect to the diagram service with a gRPC DiagramConsumerClient	SUPER_ADMIN, EWB_DIAGRAM_VIEWER

The EWB Roles will be included in a generated token's "roles" claim when the External Roles being assigned to the new token inherit their matching EAS permission.

note

This permission check only happens at token creation time and cannot be updated or revoked after the token is created.