diff --git a/content/docs/capabilities/img/service-accounts/add-service-account.png b/content/docs/capabilities/img/service-accounts/add-service-account.png new file mode 100644 index 000000000..bbdccdd5b Binary files /dev/null and b/content/docs/capabilities/img/service-accounts/add-service-account.png differ diff --git a/content/docs/capabilities/service-accounts.md b/content/docs/capabilities/service-accounts.md index b1b7e315b..34c23a617 100644 --- a/content/docs/capabilities/service-accounts.md +++ b/content/docs/capabilities/service-accounts.md @@ -1,4 +1,5 @@ --- +#cSpell:ignore etag title: Service Accounts lang: en-US keywords: @@ -12,36 +13,84 @@ keywords: ] --- -## Service Accounts +# Service Accounts Service accounts offer a protected and standardized method of authenticating machine-to-machine communication between services protected by Pomerium. -:::tip +:::enterprise -Before you begin, confirm you are in the correct Namespace. A service account can only be used in the Namespace it was created in, including its children Namespaces. +Service Accounts are a Pomerium Enterprise feature. The steps below show you how to create and use a Service Account in the Enterprise Console. See our [Pomerium Enterprise](/docs/deploy/enterprise) page for more information. ::: -1. From the main menu, select **Service Accounts** under **CONFIGURE**. Click the **+ ADD SERVICE ACCOUNT** button: +## Add a Service Account in the Enterprise Console - ![The Service Accounts page](./img/service-accounts/console-service-account.png) +Before you begin, confirm you are in the correct Namespace. You can only use a service account in the Namespace it was created in, including its children Namespaces. -1. Service accounts can be unique and exist only for Pomerium, or impersonate directory users from your IdP. +### Add a service account - Give the user a unique ID, or select an existing user to impersonate. Consider referencing the Namespace you're creating it under, for easier reference later. Optionally set an expiration date: +1. In the **Service Accounts** dashboard, select **+ ADD SERVICE ACCOUNT**: + + ![Adding a Service Account in the Global namespace in the Enterprise Console](./img/service-accounts/add-service-account.png) + +1. Give the service account a unique **User ID**, or select an existing user to impersonate. Consider referencing the Namespace you're creating it under, for easier reference later. Optionally, set an expiration date. ![Adding a unique service account](./img/service-accounts/create-service-account.png) The user ID set here corresponds to the `User` criteria when editing a policy. -1. After you click **Submit**, the modal presents the JSON web token (**JWT**) for the service account. Temporarily save it somewhere secure, as you will not be able to view it again: + :::info - ![Service Account Added](./img/service-accounts/service-account-jwt.png) + Service accounts can be unique and exist only for Pomerium, or impersonate directory users from your identity provider. + + See the following pages for more information: + + - [**Directory Sync**](/docs/capabilities/directory-sync) + - [**User Impersonation**](/docs/capabilities/impersonation) - This JWT must be added to your application configuration to enable direct communication. + ::: + +### Save the service account JWT + +1. After you select **Submit**, the modal presents the JSON web token (**JWT**) to authenticate the service account. Save it somewhere secure, as you won't be able to view it again: + + ![Service Account Added](./img/service-accounts/service-account-jwt.png) 1. Edit or create policies to give the service account access to the internal service: ![An example policy for a service account](./img/service-accounts/create-policy-1.png) ![An example policy for a service account in the policy builder](./img/service-accounts/create-policy-2.png) + +### Authenticate with the Service Account JWT + +Pomerium provides three methods to authenticate with a Service Account JWT: + +- `Authorization: Bearer Pomerium-${pomerium_jwt}` +- `X-Pomerium-Authorization: ${pomerium_jwt}` +- `Authorization: Pomerium ${pomerium_jwt}` + +For example, the curl command below demonstrates how to send an authenticated request using the bearer token method: + +```bash +curl -i -H "Accept: application/json" -H "Authorization: Bearer Pomerium-${pomerium_jwt}" +https://verify.localhost.pomerium.io +``` + +If the request is valid, the response would look similar to the example below: + +```bash +HTTP/2 200 +accept-ranges: bytes +cache-control: no-cache +content-type: text/html; charset=utf-8 +etag: "75df42fffe5e9fdf2c13f64963d04e8115fb06f8e9c4a97db3c9d7394ab6be38" +x-cloud-trace-context: 97f79dda2b32e0618d7e53cee2c85bcb;o=1 +date: Mon, 04 Mar 2024 21:56:24 GMT +server: envoy +content-length: 1191 +x-envoy-upstream-service-time: 206 +x-frame-options: SAMEORIGIN +x-xss-protection: 1; mode=block +x-request-id: bcd0bb52-25fb-4858-8da0-a552fc9b2859 +```