Skip to content

Commit a99da5d

Browse files
tronghnsindrerh2
tronghn
and
sindrerh2
committed
wip: texas out of beta
Co-Authored-By: Sindre Rødseth Hansen <[email protected]>
1 parent 6edda60 commit a99da5d

File tree

21 files changed

+203
-734
lines changed

21 files changed

+203
-734
lines changed

‎docs/auth/entra-id/how-to/consume-m2m.md

-60
Original file line numberDiff line numberDiff line change
@@ -25,75 +25,15 @@ spec:
2525
2626
Depending on how you communicate with the API you're consuming, [configure the appropriate outbound access policies](../../../workloads/how-to/access-policies.md#outbound-access).
2727
28-
{%- if tenant() == "nav" %}
29-
???+ warning "Use webproxy for outbound network connectivity from on-premises environments"
30-
31-
If you're on-premises, you must enable and use [`webproxy`](../../../workloads/application/reference/application-spec.md#webproxy) to access Entra ID.
32-
33-
{%- endif %}
34-
3528
## Acquire token
3629
3730
Now you can request a new token for the API that you want to consume.
3831
39-
To acquire a token, you can either:
40-
41-
- [acquire tokens with Texas](#acquire-tokens-with-texas), or
42-
- [acquire tokens manually](#acquire-tokens-manually) in your application
43-
44-
### Acquire tokens with Texas
45-
4632
{% set identity_provider = 'azuread' %}
4733
{% set target = 'api://<cluster>.<namespace>.<other-api-app-name>/.default' %}
4834
{% set target_description = 'The intended _audience_ (target API or recipient) of the new token.' %}
4935
{% include 'auth/partials/token.md' %}
5036
51-
### Acquire tokens manually
52-
53-
The token request is an HTTP POST request.
54-
It must have the `Content-Type` header set to `application/x-www-form-urlencoded`.
55-
56-
The body of the request should contain the following parameters:
57-
58-
| Parameter | Example Value | Description |
59-
|:----------------|:------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------|
60-
| `client_id` | `60dea49a-255b-48b5-b0c0-0974ac1c0b53` | Client identifier for your application. Set to the [`AZURE_APP_CLIENT_ID` environment variable][variables-ref]. |
61-
| `client_secret` | `<some-secret>` | Client secret for your application. Set to the [`AZURE_APP_CLIENT_SECRET` environment variable][variables-ref]. |
62-
| `grant_type` | `client_credentials` | Always `client_credentials`. |
63-
| `scope` | `api://<cluster>.<namespace>.<other-api-app-name>/.default` | The intended _audience_ (target API or recipient) of the new token. |
64-
65-
[variables-ref]: ../reference/README.md#variables-for-acquiring-tokens
66-
67-
Send the request to the `token_endpoint`, i.e. the URL found in the [`AZURE_OPENID_CONFIG_TOKEN_ENDPOINT`][variables-ref] environment variable:
68-
69-
```http title="Token request"
70-
POST ${AZURE_OPENID_CONFIG_TOKEN_ENDPOINT} HTTP/1.1
71-
Content-Type: application/x-www-form-urlencoded
72-
73-
client_id=${AZURE_APP_CLIENT_ID]&
74-
client_secret=${AZURE_APP_CLIENT_SECRET}&
75-
grant_type=client_credentials&
76-
scope=api://<cluster>.<namespace>.<other-api-app-name>/.default
77-
```
78-
79-
```json title="Successful response"
80-
{
81-
"access_token" : "eyJ0eX[...]",
82-
"expires_in" : 3599,
83-
...
84-
}
85-
```
86-
87-
Your application does not need to validate this token.
88-
89-
!!! tip "Token Caching"
90-
91-
The `expires_in` field denotes the lifetime of the token in seconds.
92-
93-
**Cache and reuse the token until it expires** to minimize network latency impact.
94-
95-
A safe cache key for this flow is `key = $scope`.
96-
9737
## Consume API
9838
9939
Once you have acquired a new token, you can finally consume the target API by using the token as a [Bearer token](../../explanations/README.md#bearer-token):

‎docs/auth/entra-id/how-to/consume-obo.md

+1-65
Original file line numberDiff line numberDiff line change
@@ -19,78 +19,14 @@ This is also known as the _on-behalf-of (OBO)_ flow.
1919

2020
Depending on how you communicate with the API you're consuming, [configure the appropriate outbound access policies](../../../workloads/how-to/access-policies.md#outbound-access).
2121

22-
{%- if tenant() == "nav" %}
23-
???+ warning "Use webproxy for outbound network connectivity from on-premises environments"
24-
25-
If you're on-premises, you must enable and use [`webproxy`](../../../workloads/application/reference/application-spec.md#webproxy) to access Entra ID.
26-
27-
{%- endif %}
28-
2922
## Exchange token
3023

31-
Now you can exchange the employees subject token for a new token targeting the API that you want to consume.
32-
33-
To exchange a token, you can either:
34-
35-
- [exchange tokens with Texas](#exchange-tokens-with-texas), or
36-
- [exchange tokens manually](#exchange-tokens-manually) in your application
37-
38-
### Exchange tokens with Texas
24+
Now you can exchange the employee's subject token for a new token, targeting the API that you want to consume.
3925

4026
{% set identity_provider = 'azuread' %}
4127
{% set target = 'api://<cluster>.<namespace>.<other-api-app-name>/.default' %}
4228
{% include 'auth/partials/token-exchange.md' %}
4329

44-
### Exchange tokens manually
45-
46-
The token request is an HTTP POST request.
47-
It must have the `Content-Type` header set to `application/x-www-form-urlencoded`.
48-
49-
The body of the request should contain the following parameters:
50-
51-
| Parameter | Example Value | Description |
52-
|:----------------------|:------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------|
53-
| `assertion` | `eyJraWQ...` | The employee's subject token from the inbound request. Token that should be exchanged. |
54-
| `client_id` | `60dea49a-255b-48b5-b0c0-0974ac1c0b53` | Client identifier for your application. Set to the [`AZURE_APP_CLIENT_ID` environment variable][variables-ref]. |
55-
| `client_secret` | `<some-secret>` | Client secret for your application. Set to the [`AZURE_APP_CLIENT_SECRET` environment variable][variables-ref]. |
56-
| `grant_type` | `urn:ietf:params:oauth:grant-type:jwt-bearer` | Always `urn:ietf:params:oauth:grant-type:jwt-bearer`. |
57-
| `requested_token_use` | `on_behalf_of` | Always `on_behalf_of`. |
58-
| `scope` | `api://<cluster>.<namespace>.<other-api-app-name>/.default` | The intended _audience_ (target API or recipient) of the new token. |
59-
60-
[variables-ref]: ../reference/README.md#variables-for-acquiring-tokens
61-
62-
Send the request to the `token_endpoint`, i.e. the URL found in the [`AZURE_OPENID_CONFIG_TOKEN_ENDPOINT`][variables-ref] environment variable:
63-
64-
```http title="Token request"
65-
POST ${AZURE_OPENID_CONFIG_TOKEN_ENDPOINT} HTTP/1.1
66-
Content-Type: application/x-www-form-urlencoded
67-
68-
assertion=<subject_token>&
69-
client_id=${AZURE_APP_CLIENT_ID}&
70-
client_secret=${AZURE_APP_CLIENT_SECRET}&
71-
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
72-
requested_token_use=on_behalf_of&
73-
scope=api://<cluster>.<namespace>.<other-api-app-name>/.default
74-
```
75-
76-
```json title="Successful response"
77-
{
78-
"access_token" : "eyJ0eX[...]",
79-
"expires_in" : 3599,
80-
...
81-
}
82-
```
83-
84-
Your application does not need to validate this token.
85-
86-
!!! tip "Token Caching"
87-
88-
The `expires_in` field denotes the lifetime of the token in seconds.
89-
90-
**Cache and reuse the token until it expires** to minimize network latency impact.
91-
92-
A safe cache key for this flow is `key = sha256($subject_token + $scope)`.
93-
9430
## Consume API
9531

9632
Once you have acquired a new token, you can finally consume the target API by using the token as a [Bearer token](../../explanations/README.md#bearer-token):

‎docs/auth/entra-id/how-to/secure.md

-9
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,6 @@ conditional: [tenant, nav]
77

88
This how-to guides you through the steps required to secure your API using [Entra ID](../README.md):
99

10-
{%- if tenant() == "nav" %}
11-
???+ warning "Use webproxy for outbound network connectivity from on-premises environments"
12-
13-
If you're on-premises, you must enable and use [`webproxy`](../../../workloads/application/reference/application-spec.md#webproxy) to access Entra ID.
14-
15-
{%- endif %}
16-
1710
## Grant access to consumers
1811

1912
Depending on who your consumers are, you must grant access to either applications, users, or both.
@@ -40,5 +33,3 @@ You will need to validate these tokens in your application.
4033
Verify incoming requests from consumers by validating the [JWT Bearer token](../../explanations/README.md#bearer-token) in the `Authorization` header.
4134

4235
{% include 'auth/entra-id/partials/validate.md' %}
43-
44-
[variables-ref]: ../reference/README.md#variables-for-validating-tokens

‎docs/auth/entra-id/partials/validate.md

+1-29
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,4 @@
11
{% set identity_provider = 'azuread' %}
22
{% set claims_reference = '../reference/README.md#claims' %}
3+
{% set token_validation_reference = '../reference/README.md#manual-token-validation' %}
34
{% include 'auth/partials/validate.md' %}
4-
5-
To validate the token, start by validating the [signature and standard time-related claims](../../explanations/README.md#token-validation).
6-
7-
Additionally, perform the following validations:
8-
9-
**Issuer Validation**
10-
11-
Validate that the `iss` claim has a value that is equal to either:
12-
13-
1. the `AZURE_OPENID_CONFIG_ISSUER` [environment variable](../reference/README.md#runtime-variables-credentials), or
14-
2. the `issuer` property from the [metadata discovery document](../../explanations/README.md#well-known-url-metadata-document).
15-
The document is found at the endpoint pointed to by the `AZURE_APP_WELL_KNOWN_URL` environment variable.
16-
17-
**Audience Validation**
18-
19-
Validate that the `aud` claim is equal to the `AZURE_APP_CLIENT_ID` environment variable.
20-
21-
**Signature Validation**
22-
23-
Validate that the token is signed with a public key published at the JWKS endpoint.
24-
This endpoint URI can be found in one of two ways:
25-
26-
1. the `AZURE_OPENID_CONFIG_JWKS_URI` environment variable, or
27-
2. the `jwks_uri` property from the metadata discovery document.
28-
The document is found at the endpoint pointed to by the `AZURE_APP_WELL_KNOWN_URL` environment variable.
29-
30-
**Claims Validation**
31-
32-
[Other claims](../reference/README.md#claims) may be present in the token. Validation of these claims is optional.

‎docs/auth/entra-id/reference/README.md

+30-22
Original file line numberDiff line numberDiff line change
@@ -217,38 +217,46 @@ We only use v2.0 tokens.
217217
Consumers defined in the [access policy](../how-to/secure.md#applications) are always assigned the default scope named `defaultaccess`.
218218
You can optionally define and grant them [custom scopes](#custom-scopes).
219219

220-
## Runtime Variables & Credentials
220+
## Manual Token Validation
221+
222+
{% include 'auth/partials/validate-manually.md' %}
223+
224+
**Issuer Validation**
225+
226+
Validate that the `iss` claim has a value that is equal to either:
221227

222-
Your application will automatically be injected with environment variables at runtime.
228+
1. the `AZURE_OPENID_CONFIG_ISSUER` environment variable, or
229+
2. the `issuer` property from the [metadata discovery document](../../explanations/README.md#well-known-url-metadata-document).
230+
The document is found at the endpoint pointed to by the `AZURE_APP_WELL_KNOWN_URL` environment variable.
223231

224-
### Variables for acquiring tokens
232+
**Audience Validation**
225233

226-
These variables are used to:
234+
Validate that the `aud` claim is equal to the `AZURE_APP_CLIENT_ID` environment variable.
227235

228-
- [:dart: consume an API as an application](../how-to/consume-m2m.md) and
229-
- [:dart: consume an API on behalf of an employee](../how-to/consume-obo.md)
236+
**Signature Validation**
230237

231-
| Name | Description |
232-
|:-------------------------------------|:-------------------------------------------------------------------------------------------------------------------------|
233-
| `AZURE_APP_CLIENT_ID` | [Client ID](../../explanations/README.md#client-id) that uniquely identifies the application in Entra ID. |
234-
| `AZURE_APP_CLIENT_SECRET` | [Client secret](../../explanations/README.md#client-secret) for the application in Entra ID. |
235-
| `AZURE_APP_WELL_KNOWN_URL` | The well-known URL for the [metadata discovery document](../../explanations/README.md#well-known-url-metadata-document). |
236-
| `AZURE_OPENID_CONFIG_TOKEN_ENDPOINT` | `token_endpoint` from the [metadata discovery document](../../explanations/README.md#token-endpoint). |
238+
Validate that the token is signed with a public key published at the JWKS endpoint.
239+
This endpoint URI can be found in one of two ways:
237240

238-
`AZURE_APP_WELL_KNOWN_URL` is optional if you're using `AZURE_OPENID_CONFIG_TOKEN_ENDPOINT` directly.
241+
1. the `AZURE_OPENID_CONFIG_JWKS_URI` environment variable, or
242+
2. the `jwks_uri` property from the metadata discovery document.
243+
The document is found at the endpoint pointed to by the `AZURE_APP_WELL_KNOWN_URL` environment variable.
239244

240-
### Variables for validating tokens
245+
**Claims Validation**
246+
247+
[Other claims](../reference/README.md#claims) may be present in the token. Validation of these claims is optional.
248+
249+
## Runtime Variables & Credentials
241250

242-
These variables are used to [:dart: secure your API](../how-to/secure.md):
251+
Your application will automatically be injected with the following environment variables at runtime.
243252

244-
| Name | Description |
245-
|:-------------------------------|:-------------------------------------------------------------------------------------------------------------------------|
246-
| `AZURE_APP_CLIENT_ID` | [Client ID](../explanations/README.md#client-id) that uniquely identifies the application in Entra ID. |
247-
| `AZURE_APP_WELL_KNOWN_URL` | The well-known URL for the [metadata discovery document](../../explanations/README.md#well-known-url-metadata-document). |
248-
| `AZURE_OPENID_CONFIG_ISSUER` | `issuer` from the [metadata discovery document](../../explanations/README.md#issuer). |
249-
| `AZURE_OPENID_CONFIG_JWKS_URI` | `jwks_uri` from the [metadata discovery document](../../explanations/README.md#jwks-endpoint-public-keys). |
253+
| Environment Variable | Description |
254+
|-------------------------------------|---------------------------------------------------------------------------------------------------------|
255+
| `NAIS_TOKEN_ENDPOINT` | Used to [:dart: consume an API as an application](../how-to/consume-m2m.md). |
256+
| `NAIS_TOKEN_EXCHANGE_ENDPOINT` | Used to [:dart: consume an API on behalf of an employee](../how-to/consume-obo.md). |
257+
| `NAIS_TOKEN_INTROSPECTION_ENDPOINT` | Used to [:dart: secure your API](../how-to/secure.md) or [:dart: log in employees](../how-to/login.md). |
250258

251-
`AZURE_APP_WELL_KNOWN_URL` is optional if you're using `AZURE_OPENID_CONFIG_ISSUER` and `AZURE_OPENID_CONFIG_JWKS_URI` directly.
259+
For further details about these endpoints, see the [OpenAPI specification](../../reference/README.md#openapi-specification).
252260

253261
## Spec
254262

‎docs/auth/explanations/README.md

+9-36
Original file line numberDiff line numberDiff line change
@@ -192,14 +192,6 @@ Unless specified otherwise, all clients we use are confidential clients.
192192
A client ID is a unique identifier associated with your client for a given identity provider. The value of the
193193
identifier is generally not considered to be confidential.
194194

195-
The client ID for your client is injected at runtime as an environment variable.
196-
See the respective identity provider page for details:
197-
198-
- [Entra ID](../entra-id/reference/README.md#runtime-variables-credentials)
199-
- [ID-porten](../idporten/reference/README.md#runtime-variables-credentials)
200-
- [Maskinporten](../maskinporten/reference/README.md#runtime-variables-credentials)
201-
- [TokenX](../tokenx/reference/README.md#runtime-variables-credentials)
202-
203195
#### Client Authentication
204196

205197
A confidential client must authenticate itself to the identity provider.
@@ -426,8 +418,6 @@ Validation should always be performed before granting access to any [resource se
426418
Use well-known and widely used libraries and frameworks that take care of most
427419
of the heavy lifting for you.
428420

429-
See [libraries and frameworks](../reference/README.md#libraries-and-frameworks-for-validating-and-acquiring-tokens) for a non-comprehensive list.
430-
431421
#### Signature Validation
432422

433423
A JWT usually contains the `kid` (key ID) claim in the token's [header](#header) to indicate which key was used to sign
@@ -467,7 +457,7 @@ Most libraries will have implementations to automatically validate these de fact
467457

468458
See the individual identity provider pages for specific validation related to each provider:
469459

470-
- [Entra ID](../entra-id/how-to/secure.md#validate-tokens)
460+
- [Entra ID](../entra-id/reference/README.md#manual-token-validation)
471461
- [ID-porten](../idporten/how-to/login.md#validate-token-in-authorization-header)
472462
- [Maskinporten](../maskinporten/how-to/secure.md#validate-tokens)
473463
- [TokenX](../tokenx/how-to/secure.md#validate-tokens)
@@ -706,40 +696,23 @@ Texas runs as a sidecar together with your application and offers HTTP endpoints
706696
- exchanging user tokens into on-behalf-of tokens
707697
- token validation with introspection
708698

709-
???+ warning "Texas is currently in opt-in public beta"
710-
711-
To enable Texas for your application, set the `texas.nais.io/enabled: "true"` annotation on your `Application`:
712-
713-
```yaml title="app.yaml" hl_lines="5"
714-
apiVersion: "nais.io/v1alpha1"
715-
kind: "Application"
716-
metadata:
717-
annotations:
718-
texas.nais.io/enabled: "true"
719-
```
720-
721-
Texas is in beta as we gather feedback and test it in production environments.
722-
We do not plan to make any breaking API changes.
723-
724-
Visit the `#texas` channel on Slack for updates, questions and feedback.
725-
726699
All available [identity providers](#identity-provider) are supported:
727700

728701
[Entra ID](../entra-id/README.md)
729-
: - [:dart: Get a machine-to-machine token](../entra-id/how-to/consume-m2m.md#acquire-tokens-with-texas)
730-
- [:dart: Exchange an on-behalf-of token](../entra-id/how-to/consume-obo.md#exchange-tokens-with-texas)
731-
- [:dart: Validate token](../entra-id/how-to/secure.md#validate-with-texas)
702+
: - [:dart: Get a machine-to-machine token](../entra-id/how-to/consume-m2m.md#acquire-token)
703+
- [:dart: Exchange an on-behalf-of token](../entra-id/how-to/consume-obo.md#exchange-token)
704+
- [:dart: Validate token](../entra-id/how-to/secure.md#validate-tokens)
732705

733706
[ID-porten](../idporten/README.md)
734-
: - [:dart: Validate token](../idporten/how-to/login.md#validate-with-texas)
707+
: - [:dart: Validate token](../idporten/how-to/login.md#validate-token-in-authorization-header)
735708

736709
[Maskinporten](../maskinporten/README.md)
737-
: - [:dart: Get a machine-to-machine token](../maskinporten/how-to/consume.md#acquire-tokens-with-texas)
738-
- [:dart: Validate token](../maskinporten/how-to/secure.md#validate-with-texas)
710+
: - [:dart: Get a machine-to-machine token](../maskinporten/how-to/consume.md#acquire-token)
711+
- [:dart: Validate token](../maskinporten/how-to/secure.md#validate-tokens)
739712

740713
[TokenX](../tokenx/README.md)
741-
: - [:dart: Exchange an on-behalf-of token](../tokenx/how-to/consume.md#exchange-tokens-with-texas)
742-
- [:dart: Validate token](../tokenx/how-to/secure.md#validate-with-texas)
714+
: - [:dart: Exchange an on-behalf-of token](../tokenx/how-to/consume.md#exchange-token)
715+
- [:dart: Validate token](../tokenx/how-to/secure.md#validate-tokens)
743716

744717
See the [Texas reference](../reference/README.md#texas) for API specifications and available environment variables.
745718

0 commit comments

Comments
 (0)