wip: texas documentation

nais · Nov 19, 2024 · cc2b935 · cc2b935
1 parent 68d81c8
commit cc2b935
Show file tree

Hide file tree

Showing 5 changed files with 153 additions and 2 deletions.
diff --git a/docs/auth/entra-id/how-to/consume-m2m.md b/docs/auth/entra-id/how-to/consume-m2m.md
@@ -33,9 +33,33 @@ Depending on how you communicate with the API you're consuming, [configure the a
 {%- endif %}
 
 ## Acquire token
-
 Now you can request a new token for the API that you want to consume.
 
+### Automatically with Texas
+???+ warning "Token Exchange as a Service (Texas) is in public beta."
+
+    To enable for your application, set the `texas.nais.io=enabled` label on your `Application`.
+
+Texas is [Token Exchange as a Service](../../explanations/README.md#texas), aimed to make it easier to deal with tokens.
+
+Send a HTTP POST request to the endpoint described in the `$NAIS_TOKEN_ENDPOINT` environment variable. The value for `target` is the identifier for the application you wish to make calls to.
+```json
+{
+    "identity_provider": "azuread",
+    "target": "cluster:namespace:application"
+}
+```
+
+You will get a response with an access token. The token can be used to access APIs for your specified target only.
+```json
+{
+    "access_token": "eyJra...",
+    "expires_in": 3599,
+    "token_type": "Bearer"
+}
+```
+
+### Manually
 The token request is an HTTP POST request.
 It must have the `Content-Type` header set to `application/x-www-form-urlencoded`.
 

diff --git a/docs/auth/entra-id/how-to/consume-obo.md b/docs/auth/entra-id/how-to/consume-obo.md
@@ -27,9 +27,38 @@ Depending on how you communicate with the API you're consuming, [configure the a
 {%- endif %}
 
 ## Acquire token
-
 Now you can exchange the employees subject token for a new token targeting the API that you want to consume.
 
+### Automatically with Texas
+
+???+ warning "Token Exchange as a Service (Texas) is in public beta."
+
+    To enable for your application, set the `texas.nais.io=enabled` label on your `Application`.
+
+Texas is [Token Exchange as a Service](../../explanations/README.md#texas), aimed to make it easier to deal with tokens.
+
+Send a HTTP POST request to the endpoint described in the `$NAIS_TOKEN_EXCHANGE_ENDPOINT` environment variable.
+The value for `target` is the identifier for the application you wish to make calls to.
+Set `user_token` to the user's access token.
+
+```json
+{
+    "identity_provider": "azuread",
+    "target": "cluster:namespace:application",
+    "user_token": "eyJra..."
+}
+```
+
+You will get a response with an access token. The token can be used to access APIs on behalf of the user, for your specified target only.
+```json
+{
+    "access_token": "eyJra...",
+    "expires_in": 3599,
+    "token_type": "Bearer"
+}
+```
+
+### Manually
 The token request is an HTTP POST request.
 It must have the `Content-Type` header set to `application/x-www-form-urlencoded`.
 

diff --git a/docs/auth/explanations/README.md b/docs/auth/explanations/README.md
@@ -695,6 +695,34 @@ Requests to these paths will pass through the proxy to your application without
 
 See the [autologin reference](../reference/README.md#autologin) for details.
 
+## Texas
+
+???+ warning "Token Exchange as a Service (Texas) is in public beta."
+
+    To enable for your application, set the `texas.nais.io=enabled` label on your `Application`.
+
+Texas is an abbreviation for *Token Exchange as a Service*, and aims to make it easier to deal with tokens.
+
+Texas offers HTTP endpoints for getting tokens, exchanging user tokens into on-behalf-of tokens, and token introspection.
+
+See the [OpenAPI v3 documentation](https://raw.githubusercontent.com/nais/texas/refs/heads/master/doc/openapi-spec.json)
+for details.
+
+### Get a machine token
+
+The token endpoint is available at `$NAIS_TOKEN_ENDPOINT`.
+Use this endpoint when you need to call another API, unless the request is behalf of a logged-in user. Use the token exchange endpoint for those cases.
+
+### Exchange a user token for a machine token
+
+The token endpoint is available at `$NAIS_TOKEN_ENDPOINT`.
+Use this endpoint when you need to call another API on behalf of a logged-in user.
+
+### Introspection
+
+The introspect endpoint is available at `$NAIS_TOKEN_INTROSPECT_ENDPOINT`.
+Introspection implies validation. *Always* validate tokens in incoming requests before handling the request.
+
 ## Further Reading
 
 - <https://nais.io/blog/posts/oauth1/>

diff --git a/docs/auth/maskinporten/how-to/consume.md b/docs/auth/maskinporten/how-to/consume.md
@@ -40,6 +40,31 @@ The scopes themselves are defined and owned by the external API provider. The ex
 
 ## Acquire token
 
+### Automatically with Texas
+???+ warning "Token Exchange as a Service (Texas) is in public beta."
+
+    To enable for your application, set the `texas.nais.io=enabled` label on your `Application`.
+
+Texas is [Token Exchange as a Service](../../explanations/README.md#texas), aimed to make it easier to deal with tokens.
+
+Send a HTTP POST request to the endpoint described in the `$NAIS_TOKEN_ENDPOINT` environment variable. The value for `target` is the identifier for the application you wish to make calls to.
+```json
+{
+    "identity_provider": "maskinporten",
+    "target": "skatt:some.scope"
+}
+```
+
+You will get a response with an access token. The token can be used to access APIs for your specified target only.
+```json
+{
+    "access_token": "eyJra...",
+    "expires_in": 3599,
+    "token_type": "Bearer"
+}
+```
+
+### Manually
 To acquire a token from Maskinporten, you will need to create a [client assertion](../../explanations/README.md#client-assertion).
 
 ### Create client assertion

diff --git a/docs/auth/partials/validate.md b/docs/auth/partials/validate.md
@@ -1,3 +1,48 @@
+**Texas**
+
+???+ warning "Token Exchange as a Service (Texas) is in public beta."
+
+    To enable for your application, set the `texas.nais.io=enabled` label on your `Application`.
+
+Texas is [Token Exchange as a Service](../../explanations/README.md#texas), aimed to make it easier to deal with tokens.
+
+Send a HTTP POST request to the endpoint described in the `$NAIS_TOKEN_INTROSPECT_ENDPOINT` environment variable.
+Set `target` to the access token you wish to validate.
+
+```json
+{
+    "identity_provider": "<IDENTITY_PROVIDER>",
+    "token": "eyJra..."
+}
+```
+
+If the token is valid, you will get a response containing all the token's claims, in addition to an extra field `active=true`:
+
+```json
+{
+    "active": true,
+    "aud": "my-target",
+    "azp": "yolo",
+    "exp": 1730980893,
+    "iat": 1730977293,
+    "iss": "http://localhost:8080/tokenx",
+    "jti": "e7cbadc3-6bda-49c0-a196-c47328da880e",
+    "nbf": 1730977293,
+    "sub": "e015542c-0f81-40f5-bbd9-7c3d9366298f",
+    "tid": "tokenx"
+}
+```
+
+On the other hand, if the token is invalid due to any reason, the response will contain the field `active=false`,
+in addition to a human-readable error message describing the situation:
+
+```json
+{
+    "active": false,
+    "error": "token is expired",
+}
+```
+
 **JWT Validation**
 
 Validating a JWT involves a number of steps.