> For the complete documentation index, see [llms.txt](https://aws-gcr-wwso-security.gitbook.io/an-quan-zui-jia-shi-jian/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aws-gcr-wwso-security.gitbook.io/an-quan-zui-jia-shi-jian/1.-iam-shen-fen-shi-bie-yu-fang-wen-kong-zhi/workforce-identity-integration-dan-dian-deng-lu/ling-pai-ren-zheng-he-dan-dian-deng-lu-xie-yi/openid-connect-oidc.md).

# OpenID Connect (OIDC)

#### OpenID Connect (OIDC)

[OpenID Connect](https://openid.net/developers/how-connect-works/) 简称OIDC，是基于OAuth 2.0扩展而来的一个协议。除了能够实现OAuth 2.0中的认证场景，还额外定义了认证的场景。相比OAuth 2.0，OIDC引入了id\_token和userinfo相关的概念。OIDC引入了身份令牌(ID Token)的概念，用这个特殊的令牌来确定资源所有者的身份。

**Key Concepts:**

* **ID Token:** A JWT that contains the user's profile information and is provided upon successful authentication.
* **Authentication Request:** Clients request user authentication and ID tokens from the authorization server.
* **UserInfo Endpoint:** A protected resource that, when accessed with an access token, returns claims about the authenticated user.

OIDC定义了类似SAML Metadata的Discovery端口，俗称周知端口(well-known port)。详细说明可参考以下网址中的内容。

<https://openid.net/specs/openid-connect-discovery-1_0.html>［2022-8-13］

OIDC协议的登录授权流程和OAuth 2.0类似，整个流程的参与者也类似，只不过换了两个术语：OpenID提供者(OpenID Provider，OP)，负责认证和授权服务；依赖方(Relying Party，RP)，是OAuth 2.0中的客户端。

OIDC完全兼容OAuth 2.0，在API资源需要包含的场景下可以使用访问令牌控制受保护的API资源。OIDC可以兼容众多的身份提供者，并且作为其他认证中心的父级的身份提供者来使用。

OIDC的一些敏感接口均强制要求TLS，除此之外，得益于JWT、JWS、JWE家族的安全机制，使得一些敏感信息可以进行数字签名、加密和验证，进一步保障整个认证过程的安全。

{% @mermaid/diagram content="sequenceDiagram
客户端 ->> APP: 访问应用<http://app.com>
APP ->>APP: 2.APP检查有无用户登录信息，启动认证流程
Note right of APP: response\_type=code<br/>\&client\_id=CLIENT\_ID<br/>\&redirect\_uri=REDIRECT\_URI<br/>\&scope=photos<br/>\&state=1234zyx
APP ->>浏览器: 3.重定向命令
浏览器 ->>浏览器: 4.浏览器重定向
浏览器 ->>SSO服务器: 5. 浏览器访问： <http://sso.com/oidc/auth?PAPM>
SSO服务器 ->>SSO服务器: 6.SSO服务器检查有无用户，进入登录页面
SSO服务器 -->>浏览器: 7.跳转到登录页面
浏览器 -->>APP: 8.显示登录页面
APP ->>APP: 9.输入验证信息
APP ->>浏览器: 10.提交登录信息
浏览器 ->>SSO服务器: 11. 登录页面提交请求：<http://sso.com/dologin>
SSO服务器 ->>SSO服务器: 12.验证用户信息，生成TGT
SSO服务器 -->>浏览器:
浏览器 ->>浏览器: 13.浏览器重定向
浏览器 ->>SSO服务器:
SSO服务器 ->>SSO服务器: 14.重新跳转到OAuth流程
SSO服务器 -->>浏览器: 15.重定向命令 <http://sso.com/oidc/auth?PAPM>
Note right of 浏览器: response\_type=code<br/>\&client\_id=CLIENT\_ID<br/>\&redirect\_uri=REDIRECT\_URI<br/>\&scope=photos<br/>\&state=1234zyx
浏览器 ->>浏览器: 16.浏览器重定向
浏览器 ->>SSO服务器: 17.浏览器访问 <http://sso.com/oidc/auth?PAPM>
SSO服务器 ->>SSO服务器: 18.生成授权码，回调
SSO服务器 -->>浏览器: 19.重定向命令 <http://app.com/code=xxx>
浏览器 ->>浏览器: 20.浏览器重定向
浏览器 -->>APP: 21.浏览器访问：<http://app.com/callback/code=xxx>
APP ->>APP: 22.APP获取授权码，POST方式向SSO请求访问令牌
APP ->>SSO服务器: 23.POST请求<http://sso.com/oide/accessToken?PAPM>
SSO服务器 ->>SSO服务器: 24.验证信息，返回令牌
SSO服务器 -->>APP:  25.返回access\_token=TGT-XXX\&id\_token=eyehbxxx\&expire=TIMEOUT
APP ->>APP: 26.APP获取访问令牌和身份令牌并保存，获取JWT验证身份令牌
APP ->>SSO服务器: 27.POST请求<http://sso.com/oidc/jwks>
SSO服务器 ->>SSO服务器: 28.读取JWT文件，生成JSON数据返回
SSO服务器 -->>APP:  29.返回JWKS JSON
APP ->>APP: 30.APP获取JWT身份令牌，并获取身份令牌中的用户信息
APP ->>浏览器: 31.返回APP页面，建立会话
浏览器 -->>客户端: 32.显示应用界面" %}

#### GitHub OIDC Token Payload

```
{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo:environment:prod",
  "environment": "prod",
  "aud": "https://github.com/octo-org",
  "ref": "refs/heads/main",
  "sha": "example-sha",
  "repository": "octo-org/octo-repo",
  "repository_owner": "octo-org",
  "actor_id": "12",
  "repository_visibility": "private",
  "repository_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "runner_environment": "github-hosted"
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}
```

#### Summary

The payload of the provided OIDC token contains several key pieces of information relevant to GitHub workflow execution, securely identifying the workflow run and related data through JWT standards.

* **Issuer (`iss`)**: The token is issued by `https://token.actions.githubusercontent.com`, ensuring its validation and integrity.
* **Subject (`sub`)**: Identifies the subject of the token as `repo:octo-org/octo-repo:environment:prod`, specifying the repository and its environment.
* **Audience (`aud`)**: The intended recipient of the token, `https://github.com/octo-org`, aligning with the GitHub organization involved.
* **Repository Details**: The payload includes detailed identifiers like `repository`, `repository_owner`, `repository_id`, and `repository_visibility`, pinpointing the exact repository and its ownership.
* **Workflow and Run Details**: It contains specific information about the workflow run, including `run_id`, `run_number`, `run_attempt`, and the workflow name, facilitating traceability of the execution.
* **Actor and Actions**: Detailing the actor (`actor_id`, `actor`) and the action taken (`event_name`), it provides auditability and context for the executable actions.
* **Timing**: The token includes timestamps for when it was issued (`iat`), when it starts being valid (`nbf`), and when it expires (`exp`), ensuring timely and secure execution of actions.

This JWT plays a crucial role in securing and documenting actions within GitHub's automation and workflows, leveraging the OIDC standard for authentication and information sharing.

## 参考资料

github - [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)

For further information on OIDC and GitHub Actions, please see:

* [AWS docs: Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
* [GitHub docs: About security hardening with OpenID Connect](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
* [GitHub docs: Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)
* [GitHub changelog: GitHub Actions: Secure cloud deployments with OpenID Connect](https://github.blog/changelog/2021-10-27-github-actions-secure-cloud-deployments-with-openid-connect/)