Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(configuration/authentication): add k8s troubleshooting documentation for discovery URL #200

Merged
merged 7 commits into from
Apr 9, 2024
Merged

chore(configuration/authentication): add k8s troubleshooting documentation for discovery URL #200

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0aaf4ea
chore(configuration/authentication): add k8s troubleshooting document…
GeorgeMac Apr 5, 2024
9395c42
chore: format code
GeorgeMac Apr 5, 2024
e909dcf
Merge branch 'main' into gm/k8s-discovery-url
GeorgeMac Apr 5, 2024
6faf964
Update configuration/authentication.mdx
markphelps Apr 8, 2024
be9c92e
Update configuration/authentication.mdx
markphelps Apr 8, 2024
c2f8d85
Merge branch 'main' into gm/k8s-discovery-url
markphelps Apr 8, 2024
5905f1e
chore: apply suggestions from code review
GeorgeMac Apr 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions configuration/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -366,6 +366,37 @@

Further explanation for using this method can be found in the [Authentication: Kubernetes](/authentication/methods#kubernetes) documentation.

#### Troubleshooting

**verifying service account: failed to verify signature: fetching keys oidc**

In some managed Kubernetes cluster environments, the default cluster OIDC provider is replaced with the platform's managed alternative.
For example, EKS clusters leverage this so that they can issue service account tokens which can assume the capabilities of AWS IAM roles.

Check warning on line 374 in configuration/authentication.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.So] Don't start a sentence with 'so '

Raw Output:
{"message": "[Openly.So] Don't start a sentence with 'so '", "location": {"path": "configuration/authentication.mdx", "range": {"start": {"line": 374, "column": 41}}}, "severity": "WARNING"}

In this situation, the default OIDC discovery URL isn't appropriate for fetching key material from.

Check warning on line 376 in configuration/authentication.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.

Raw Output:
{"message": "[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.", "location": {"path": "configuration/authentication.mdx", "range": {"start": {"line": 376, "column": 47}}}, "severity": "WARNING"}
Instead, you should locate your clusters OIDC URL and use that instead.

Check warning on line 377 in configuration/authentication.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.

Raw Output:
{"message": "[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.", "location": {"path": "configuration/authentication.mdx", "range": {"start": {"line": 377, "column": 47}}}, "severity": "WARNING"}

<Note>
Your cluster's OIDC URL will vary between Kubernetes providers. For example,

Check warning on line 380 in configuration/authentication.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.

Raw Output:
{"message": "[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.", "location": {"path": "configuration/authentication.mdx", "range": {"start": {"line": 380, "column": 23}}}, "severity": "WARNING"}

Check warning on line 380 in configuration/authentication.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "configuration/authentication.mdx", "range": {"start": {"line": 380, "column": 27}}}, "severity": "WARNING"}

Check warning on line 380 in configuration/authentication.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.SentenceLength] Write short sentences (less than 25 words).

Raw Output:
{"message": "[Openly.SentenceLength] Write short sentences (less than 25 words).", "location": {"path": "configuration/authentication.mdx", "range": {"start": {"line": 380, "column": 67}}}, "severity": "WARNING"}
here is some documentation which should help for EKS: [EKS troubleshoot OIDC

Check warning on line 381 in configuration/authentication.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.Clarity] Consider using 'assist' instead of 'help'

Raw Output:
{"message": "[Openly.Clarity] Consider using 'assist' instead of 'help'", "location": {"path": "configuration/authentication.mdx", "range": {"start": {"line": 381, "column": 43}}}, "severity": "WARNING"}
and IRSA](https://repost.aws/knowledge-center/eks-troubleshoot-oidc-and-irsa).
</Note>

It's also important to note that custom OIDC providers likely will use HTTPS which has been signed with certificates not authorized by the cluster TLS certificate authority.

Check warning on line 385 in configuration/authentication.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.SentenceLength] Write short sentences (less than 25 words).

Raw Output:
{"message": "[Openly.SentenceLength] Write short sentences (less than 25 words).", "location": {"path": "configuration/authentication.mdx", "range": {"start": {"line": 385, "column": 1}}}, "severity": "WARNING"}

Check warning on line 385 in configuration/authentication.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.So] Don't start a sentence with 'so '

Raw Output:
{"message": "[Openly.So] Don't start a sentence with 'so '", "location": {"path": "configuration/authentication.mdx", "range": {"start": {"line": 385, "column": 8}}}, "severity": "WARNING"}

Check warning on line 385 in configuration/authentication.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.Hedging] Consider removing 'likely'

Raw Output:
{"message": "[Openly.Hedging] Consider removing 'likely'", "location": {"path": "configuration/authentication.mdx", "range": {"start": {"line": 385, "column": 56}}}, "severity": "WARNING"}
In this situation, you can override the `kubernetes` auth providers `ca_path` field with relevant key material.
The `flipt` distributed Docker image has valid and trusted certificates in `/etc/ssl/certs/ca-certificates.crt`, which can be appropriate if your OIDC provider has certificates granted by a valid public certificate authority.

```yaml example-config-for-eks.yaml
authentication:
methods:
kubernetes:
enabled: true
discovery_url: https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E # note: yours will be different
ca_path: /etc/ssl/certs/ca-certificates.crt # this can be enough if your OIDC provider TLS certificates have been signed by a public certificate authority
```

See [this issue](https://github.com/flipt-io/flipt/issues/2942) for more context.

### JSON Web Token

The `jwt` method provides the ability to authenticate with Flipt using an externally issued JSON Web Token. This method is useful for integrating with other authentication systems that can issue JWTs (e.g. [Auth0](https://auth0.com/docs/tokens/json-web-tokens)) or by generating your own signed JWTs on the fly.
Expand Down
Loading