|
| 1 | +--- |
| 2 | +title: "Authentication and authorization" |
| 3 | +linkTitle: "Authentication and authorization" |
| 4 | +weight: 3 |
| 5 | +description: > |
| 6 | + This page describes about PipeCD Authentication and Authorization. |
| 7 | +--- |
| 8 | + |
| 9 | + |
| 10 | + |
| 11 | +### Static Admin |
| 12 | + |
| 13 | +When the PipeCD owner [adds a new project](../adding-a-project/), an admin account will be automatically generated for the project. After that, PipeCD owner sends that static admin information including username, password strings to the project admin, who can use that information to log in to PipeCD web with the admin role. |
| 14 | + |
| 15 | +After logging, the project admin should change the provided username and password. Or disable the static admin account after configuring the single sign-on for the project. |
| 16 | + |
| 17 | +### Single Sign-On (SSO) |
| 18 | + |
| 19 | +Single sign-on (SSO) allows users to log in to PipeCD by relying on a trusted third-party service. |
| 20 | + |
| 21 | +The project can be configured to use a shared SSO configuration (shared OAuth application) instead of needing a new one. In that case, while creating the project, the PipeCD owner specifies the name of the shared SSO configuration should be used, and then the project admin can skip configuring SSO at the settings page. |
| 22 | + |
| 23 | +**Supported service** |
| 24 | + |
| 25 | +- GitHub |
| 26 | +- Generic OIDC |
| 27 | + |
| 28 | +> Note: In the future, we want to support such as Google Gmail, Bitbucket... |
| 29 | +
|
| 30 | +#### Github |
| 31 | + |
| 32 | +Before configuring the SSO, you need an OAuth application of the using service. For example, GitHub SSO requires creating a GitHub OAuth application as described in this page: |
| 33 | + |
| 34 | +https://docs.github.com/en/developers/apps/creating-an-oauth-app |
| 35 | + |
| 36 | +The authorization callback URL should be `https://YOUR_PIPECD_ADDRESS/auth/callback`. |
| 37 | + |
| 38 | + |
| 39 | + |
| 40 | +#### Generic OIDC |
| 41 | + |
| 42 | +PipeCD supports any OIDC provider, with tested providers including Keycloak, Auth0, and AWS Cognito. The only supported authentication flow currently is the Authorization Code Grant. |
| 43 | + |
| 44 | +Requirements and Troubleshooting: |
| 45 | + |
| 46 | +- The OIDC provider must provide claims for user's roles and username. |
| 47 | +- Roles claim value must use same values as pre-configured project RBAC Roles. |
| 48 | +- - Claims can be retreived from the IdToken or UserInfo endpoint. The UserInfo endpoint will be used if issuer supports it. |
| 49 | +- You can use set a custom claim key name for roles and username in the OIDC provider. Using `usernameClaimKey` and `rolesClaimKey` in the configuration. If not set, the default value will be chosen in the following order: |
| 50 | + |
| 51 | + - Supported Claims Key for Username (in order of priority): `username`, `preferred_username`,`name`, `cognito:username` |
| 52 | + - Supported Claims Key for Role (in order of priority): `groups`, `roles`, `cognito:groups`, `custom:roles`, `custom:groups` |
| 53 | + |
| 54 | +- If no usable claims are found, `Unable to find user` error will be shown. |
| 55 | +- If no roles are found, user can not access any resources. (If `allowStrayAsViewer` is set to `true`, user can access as a viewer) |
| 56 | + |
| 57 | +Provider Configuration Examples: |
| 58 | + |
| 59 | +##### Keycloak |
| 60 | + |
| 61 | +- **Client authentication**: On |
| 62 | +- **Valid redirect URIs**: `https://YOUR_PIPECD_ADDRESS/auth/callback` |
| 63 | +- **Client scopes**: Add a new mapper to the `<client-id>-dedicated` scope. For instance, map Group Membership information to the groups claim (Full group path should be off). |
| 64 | + |
| 65 | +- **Control Plane configuration**: |
| 66 | + |
| 67 | + ```yaml |
| 68 | + apiVersion: "pipecd.dev/v1beta1" |
| 69 | + kind: ControlPlane |
| 70 | + spec: |
| 71 | + sharedSSOConfigs: |
| 72 | + - name: oidc |
| 73 | + provider: OIDC |
| 74 | + oidc: |
| 75 | + clientId: <CLIENT_ID> |
| 76 | + clientSecret: <CLIENT_SECRET> |
| 77 | + issuer: https://<KEYCLOAK_ADDRESS>/realms/<REALM> |
| 78 | + redirectUri: https://<PIPECD_ADDRESS>/auth/callback |
| 79 | + scopes: |
| 80 | + - openid |
| 81 | + - profile |
| 82 | + ``` |
| 83 | +
|
| 84 | +##### Okta |
| 85 | +
|
| 86 | +- **Allowed Callback URLs**: `https://YOUR_PIPECD_ADDRESS/auth/callback` |
| 87 | +- **Control Plane configuration**: |
| 88 | + |
| 89 | + ```yaml |
| 90 | + apiVersion: "pipecd.dev/v1beta1" |
| 91 | + kind: ControlPlane |
| 92 | + spec: |
| 93 | + sharedSSOConfigs: |
| 94 | + - name: oidc |
| 95 | + provider: OIDC |
| 96 | + oidc: |
| 97 | + clientId: <CLIENT_ID> |
| 98 | + clientSecret: <CLIENT_SECRET> |
| 99 | + issuer: https://<OKTA_ID>.okta.com |
| 100 | + redirectUri: https://<PIPECD_ADDRESS>/auth/callback |
| 101 | + scopes: |
| 102 | + - openid |
| 103 | + - profile |
| 104 | + - groups |
| 105 | + ``` |
| 106 | + |
| 107 | +##### Auth0 |
| 108 | + |
| 109 | +- **Allowed Callback URLs**: `https://YOUR_PIPECD_ADDRESS/auth/callback` |
| 110 | +- **Control Plane configuration**: |
| 111 | + |
| 112 | + ```yaml |
| 113 | + apiVersion: "pipecd.dev/v1beta1" |
| 114 | + kind: ControlPlane |
| 115 | + spec: |
| 116 | + sharedSSOConfigs: |
| 117 | + - name: oidc |
| 118 | + provider: OIDC |
| 119 | + oidc: |
| 120 | + clientId: <CLIENT_ID> |
| 121 | + clientSecret: <CLIENT_SECRET> |
| 122 | + issuer: https://<AUTH0_ADDRESS> |
| 123 | + redirectUri: https://<PIPECD_ADDRESS>/auth/callback |
| 124 | + scopes: |
| 125 | + - openid |
| 126 | + - profile |
| 127 | + ``` |
| 128 | + |
| 129 | +- **Roles/Groups Claims** |
| 130 | + For Role or Groups information mapping using Auth0 Actions, here is an example for setting `custom:roles`: |
| 131 | + |
| 132 | + ```javascript |
| 133 | + exports.onExecutePostLogin = async (event, api) => { |
| 134 | + let namespace = "custom"; |
| 135 | + if (namespace && !namespace.endsWith("/")) { |
| 136 | + namespace += ":"; |
| 137 | + } |
| 138 | + api.idToken.setCustomClaim(namespace + "roles", event.authorization.roles); |
| 139 | + }; |
| 140 | + ``` |
| 141 | + |
| 142 | +##### AWS Cognito |
| 143 | + |
| 144 | +- **Allowed Callback URLs**: `https://YOUR_PIPECD_ADDRESS/auth/callback` |
| 145 | + |
| 146 | +- **Control Plane configuration**: |
| 147 | + |
| 148 | + ```yaml |
| 149 | + apiVersion: "pipecd.dev/v1beta1" |
| 150 | + kind: ControlPlane |
| 151 | + spec: |
| 152 | + sharedSSOConfigs: |
| 153 | + - name: oidc |
| 154 | + provider: OIDC |
| 155 | + oidc: |
| 156 | + clientId: <CLIENT_ID> |
| 157 | + clientSecret: <CLIENT_SECRET> |
| 158 | + issuer: https://cognito-idp.<AWS_REGION>.amazonaws.com/<USER_POOL_ID> |
| 159 | + redirectUri: https://<PIPECD_ADDRESS>/auth/callback |
| 160 | + scopes: |
| 161 | + - openid |
| 162 | + - profile |
| 163 | + ``` |
| 164 | + |
| 165 | +##### Custom Claims Key |
| 166 | + |
| 167 | +In some cases, the OIDC provider may not provide the claims with the default key names like `groups`. You can set the custom claim key name for roles and username in the control plane configuration to map the claims from the OIDC provider. **To be cautious, OIDC providers can not be used if issuer discovery is not supported.** |
| 168 | + |
| 169 | +```yaml |
| 170 | +apiVersion: "pipecd.dev/v1beta1" |
| 171 | +kind: ControlPlane |
| 172 | +spec: |
| 173 | + sharedSSOConfigs: |
| 174 | + - name: oidc |
| 175 | + provider: OIDC |
| 176 | + oidc: |
| 177 | + clientId: <CLIENT_ID> |
| 178 | + clientSecret: <CLIENT_SECRET> |
| 179 | + issuer: https://<OIDC_ADDRESS> |
| 180 | + redirectUri: https://<PIPECD_ADDRESS>/auth/callback |
| 181 | + scopes: |
| 182 | + - openid |
| 183 | + - profile |
| 184 | + usernameClaimKey: username # change to your custom claim key |
| 185 | + rolesClaimKey: roles # change to your custom claim key |
| 186 | + avatarUrlClaimKey: picture # change to your custom claim key |
| 187 | +``` |
| 188 | + |
| 189 | +(Optional) You can choose to use the avatar URL from the OIDC provider. Using `avatarUrlClaimKey` in the configuration. If not set, the default value will be chosen in the following order: `picture`, `avatar_url` |
| 190 | + |
| 191 | +##### Custom OIDC Configuration |
| 192 | + |
| 193 | +If you want to set your custom endpoint without using the endpoint from the issuer, you can set the `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint` in the control plane configuration. |
| 194 | + |
| 195 | +```yaml |
| 196 | +apiVersion: "pipecd.dev/v1beta1" |
| 197 | +kind: ControlPlane |
| 198 | +spec: |
| 199 | + sharedSSOConfigs: |
| 200 | + - name: oidc |
| 201 | + provider: OIDC |
| 202 | + oidc: |
| 203 | + clientId: <CLIENT_ID> |
| 204 | + clientSecret: <CLIENT_SECRET> |
| 205 | + issuer: https://<OIDC_ADDRESS> |
| 206 | + redirectUri: https://<PIPECD_ADDRESS>/auth/callback |
| 207 | + scopes: |
| 208 | + - openid |
| 209 | + - profile |
| 210 | + authorization_endpoint: https://<OIDC_ADDRESS>/authorize # change to your custom endpoint |
| 211 | + token_endpoint: https://<OIDC_ADDRESS>/token # change to your custom endpoint |
| 212 | + userinfo_endpoint: https://<OIDC_ADDRESS>/userinfo # change to your custom endpoint |
| 213 | +``` |
| 214 | + |
| 215 | +### Role-Based Access Control (RBAC) |
| 216 | + |
| 217 | +Role-based access control (RBAC) allows restricting access on the PipeCD web-based on the roles of user groups within the project. Before using this feature, the SSO must be configured. |
| 218 | + |
| 219 | +PipeCD provides three built-in roles: |
| 220 | + |
| 221 | +- `Viewer`: has only permissions to view existing resources or data. |
| 222 | +- `Editor`: has all viewer permissions, plus permissions for actions that modify state, such as manually syncing application, canceling deployment... |
| 223 | +- `Admin`: has all editor permissions, plus permissions for updating project configurations. |
| 224 | + |
| 225 | +#### Configuring the PipeCD's roles |
| 226 | + |
| 227 | +The below table represents PipeCD's resources with actions on those resources. |
| 228 | + |
| 229 | +| resource | get | list | create | update | delete | |
| 230 | +| :---------- | :-: | :--: | :----: | :----: | :----: | |
| 231 | +| application | ○ | ○ | ○ | ○ | ○ | |
| 232 | +| deployment | ○ | ○ | | ○ | | |
| 233 | +| event | | ○ | | | | |
| 234 | +| piped | ○ | ○ | ○ | ○ | | |
| 235 | +| project | ○ | | | ○ | | |
| 236 | +| apiKey | | ○ | ○ | ○ | | |
| 237 | +| insight | ○ | | | | | |
| 238 | + |
| 239 | +Each role is defined as a combination of multiple policies under this format. |
| 240 | + |
| 241 | +``` |
| 242 | +resources=RESOURCE_NAMES;actions=ACTION_NAMES |
| 243 | +``` |
| 244 | +
|
| 245 | +The `*` represents all resources and all actions for a resource. |
| 246 | +
|
| 247 | +``` |
| 248 | +resources=*;actions=ACTION_NAMES |
| 249 | +resources=RESOURCE_NAMES;actions=* |
| 250 | +resources=*;actions=* |
| 251 | +``` |
| 252 | +
|
| 253 | +#### Configuring the PipeCD's user groups |
| 254 | +
|
| 255 | +User Group represents a relation with a specific team (GitHub)/group (Google) and an arbitrary role. All users belong to a team/group will have all permissions of that team/group. |
| 256 | +
|
| 257 | +In case of using the GitHub team as a PipeCD user group, the PipeCD user group must be set in lowercase. For example, if your GitHub team is named `ORG/ABC-TEAM`, the PipeCD user group would be set as `ORG/abc-team`. (It's follow the GitHub team URL as github.com/orgs/{organization-name}/teams/{TEAM-NAME}) |
| 258 | +
|
| 259 | +Note: You CANNOT assign multiple roles to a team/group, should create a new role with suitable permissions instead. |
| 260 | +
|
| 261 | + |
0 commit comments