Updating APIML OIDC support with Microsoft Entra ID details #3263
Conversation
|
|
||
|
|
||
| ## Tips | ||
| API ML Gateway exposes validate token `POST /gateway/api/v1/auth/oidc-token/validate` operation which is suitable during the OIDC setup. It expects JSON `{ token, serviceId }`. Call allows to verify that OIDC token is trusted by the API ML. Accounts mapping step is not included in that flow. |
There was a problem hiding this comment.
Please describe in other words. I do not understand "Call allows to verify..."
There was a problem hiding this comment.
Call to the endpoint /gateway/api/v1/auth/oidc-token/validate allows to verify
|
|
||
|
|
||
| ## Tips | ||
| API ML Gateway exposes validate token `POST /gateway/api/v1/auth/oidc-token/validate` operation which is suitable during the OIDC setup. It expects JSON `{ token, serviceId }`. Call allows to verify that OIDC token is trusted by the API ML. Accounts mapping step is not included in that flow. |
There was a problem hiding this comment.
What is the "flow" in this context?
There was a problem hiding this comment.
OIDC is handled via different flows through the applications and involved services.
This statement means that if you call /gateway/api/v1/auth/oidc-token/validate endpoint the Gateway service won't do the mapping request to the ESM.
|
|
||
| ## Azure Entra ID OIDC notes | ||
| At the current version API ML uses `sub` claim of the ID Token is used to identify the user and map to MF account. [Azure ID token](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#use-claims-to-reliably-identify-a-user) contains several user identifiers. Azure token `sub` is unique per each app alphanumeric value e.g. `vkDzPtDkdH1qjI9h1N1dcEqCkhVASuXLqMDtykPZhC0` whereas OKTA ID token has email in `sub` claim. So z/OS identity propagation setup should take this into account for proper account mapping configuration. See Azure clarification: | ||
| > To correctly store information per-user, use sub or oid alone (which as GUIDs are unique), with tid used for routing or sharding if needed. If you need to share data across services, oid and tid is best as all apps get the same oid and tid claims for a user acting in a tenant. The sub claim is a pair-wise value that's unique. The value is based on a combination of the token recipient, tenant, and user. Two apps that request ID tokens for a user __receive different sub claims__, but the same oid claims for that user. |
There was a problem hiding this comment.
Provide an example of storing information per user for sub and for oid alone.
Describe what "with tid" means and when it is used.
Describe what sharding is.
Is tid an alternative to oid?
What does pair-wise mean when describing the sub claim? What is the value of it being unique?
What does "Two apps that request ID tokens for a user receive different subclaims mean? Please explain in more detail.
Please rewrite this tip and resubmit for review.
| API ML Gateway exposes validate token `POST /gateway/api/v1/auth/oidc-token/validate` operation which is suitable during the OIDC setup. It expects JSON `{ token, serviceId }`. Call allows to verify that OIDC token is trusted by the API ML. Accounts mapping step is not included in that flow. | ||
|
|
||
| ## Azure Entra ID OIDC notes | ||
| At the current version API ML uses `sub` claim of the ID Token is used to identify the user and map to MF account. [Azure ID token](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#use-claims-to-reliably-identify-a-user) contains several user identifiers. Azure token `sub` is unique per each app alphanumeric value e.g. `vkDzPtDkdH1qjI9h1N1dcEqCkhVASuXLqMDtykPZhC0` whereas OKTA ID token has email in `sub` claim. So z/OS identity propagation setup should take this into account for proper account mapping configuration. See Azure clarification: |
There was a problem hiding this comment.
What is "the current version API ML"? Please be more specific. I do not understand the structure of this sentence.
- Define what is the sub claim.
- Clearly describe the difference between the Azure token sub and the OKTA ID token.
- Provide an example in z/OS identity propagation setup of how the Azure token sub and the OKTA ID token are configured.
- Remove the sentence "So z/OS identity propagation setup should take this into account for proper account mapping configuration". This is too vague.
- Remove "See Azure clarification". If there is a document that explains Azure, reference the title of the document without a link.
Please re-write.
There was a problem hiding this comment.
I main statement here is that Azure OIDC token differ from OKTA OIDC token and exactly field which we use for account mapping has different logical value in there. I put reference to MS documents where all this described. No citation anymore.
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Signed-off-by: Andrew Jandacek <[email protected]>
Your checklist for this pull request
🚨Please review the guidelines for contributing to this repository.
If the changes in this PR is part of the next future release, make this pull request against the docs-staging branch which will be published at the next release boundary. If the changes in this PR are part of the current release, use the default base branch, master. For more information about branches, see https://github.com/zowe/docs-site/tree/master#understanding-the-doc-branches.
If this PR relates to GitHub issues in
docs-siteor other repositories, please list in Description, prefixed with close, fix or resolve keywords.Description (including links to related git issues)
Please describe your pull request.
❤️Thank you!