OIDC for pipelines

Success

In this article we provide general information about integrating CI/CD pipelines in Buddy using the OIDC (OpenID Connect) identity layer. For configuration details on a specific OIDC provider, read these articles:

Hint

Learn how to configure OIDC for SSO workspace authentication.

How it works

CI/CD pipelines are designed to access cloud providers' resources in order to deploy software and use cloud services. To access these resources, one need to provide appropriate credentials (token or password). However, hardcoded secrets must be rotated on regular basis, and one has to ensure that nobody else is able to access them, which makes them less secure than short-living tokens, whose most popular form is OpenID Connect.

In the example below, service A (Buddy) is going to generate short-living tokens in service B (Azure). To do that, we first need to create an OIDC trust in service B (a one-time operation).

Every time Buddy requires a token, it generates an OIDC token with claims to the Azure OIDC trust.
Using this token service, Buddy asks Azure for a short-living credential to the Azure API.
Azure validates the claims in the token against the rules allowed in the OIDC trust and returns a short-living token with permissions matching the request.

Success

Benefits of OIDC authentication:

No hardcoded secrets
Auto-rotating credentials
Granular control over authentication and authorization

OpenID claims

Buddy asks for a short-living token before every action involving an OIDC integration. Every request for short-living credentials contains an JWT (JSON Web Token) with a series of claims. Basing on these claims, the cloud provider performs authentication and authorization.

Warning

A wrongly configured OIDC trust in a cloud provider can grant access to your resources to unauthorized persons. It is extremely important to properly configure the rules basing on OIDC claims. Follow this guidelines below to learn how.

Example JWT token

json
"header": {
        "alg": "RS256",
        "typ": "JWT",
        "kid": "be8e6e920c6d0971324fe704fdc3f7ddace29b6ded7495fb5830eec3953b3d69"
    },
    "payload": {
        "iss": "https://oidc.buddyusercontent.com",
        "sub": "domain/L39J4q2VolejO3K5ajNmGQBW71",
        "aud": "https://app.buddy.works/domain",
        "iat": 1676623065620,
        "exp": 1676626665620,
        "nbf": 1676623065619,
        "jti": "9b9c0df8-7368-47f5-9102-c6d3cae33121",
        "workspace_domain": "domain",
        "workspace_display_name": "workspace name",
        "project_name": "project",
        "project_display_name": "project name",
        "pipeline_id": 123,
        "pipeline_name": "pipeline name",
        "action_id": 456,
        "action_name": "action name",
        "execution_id": 789,
        "triggered_on": "CLICK",
        "priority": "NORMAL",
        "revision": "48rtrwy3y4wr9et4rwet",
        "ref": "master",
        "ref_type": "branch",
        "creator_id": 1,
        "creator_name": "Mike Benson"
    }

Name	Value/Example
iss The issuer of the OIDC identity provider	`https://oidc.buddyusercontent.com` (US) or `https://eu-oidc.buddyusercontent.com` (EU)
sub The subject of the OIDC identity provider	`$WORKSPACE_DOMAIN/$INTEGRATION_ID` Example: `domain/L39J4q2VolejO3K5ajNmGQBW71`
aud The audience of the OIDC identity provider	`https://app.buddy.works/$WORKSPACE_DOMAIN` (US) or `https://eu.buddy.works/$WORKSPACE_DOMAIN` (EU)
iat The issue timestamp of the token	Example: `1676623065620`
exp The expiration date of the token	Example: `1676626665620`
nbf The time before which the token must not be used	Example: `1676623065619`
jti The unique ID of the token	Example: `9b9c0df8-7368-47f5-9102-c6d3cae33121`
workspace_domain The domain of the workspace	Example: `domain`
workspace_display_name The name of the workspace as displayed on the workspace list	Example: `workspace name`
project_name The name of the project	Example: `project`
project_display_name The name of the project as displayed on the project list	Example: `project name`
pipeline_id The ID of the pipeline	Example: `123`
pipeline_name The name of the pipeline	Example: `pipeline name`
action_id The ID of the action	Example: `456`
action_name The name of the action	Example: `action name`
execution_id The ID of the current pipeline run	Example: `789`
triggered_on The trigger mode used to run the pipeline run	`CLICK`, `EVENT`, or `SCHEDULE`
priority The priority of the pipeline run.	`LOW`, `NORMAL`, `HIGH`
revision The SHA1 hash of the commit of the current pipeline run	Example: `48rtrwy3y4wr9et4rwet`
ref The branch/tag/pull request or a wildcard string for which the pipeline was run	Example: `master`
ref_type The type of ref for which the pipeline was run	Example: `branch`
creator_id The ID of the pipeline run invoker.	Example: `1`
creator_name The name of the pipeline run invoker.	Example: `Mike Benson`

Tip

When configuring the identity provider, the most important thing is to validate the claim for subject: $WORKSPACE_DOMAIN/$INTEGRATION_ID. This way you can be sure that the token is restricted to one specific integration.

Danger

Incorrect claim validation may provide unauthorized personnel with an opportunity to generate tokens on your behalf. For example, if you terminate your workspace, its domain is released and made available for other Buddy users. If you set your validation on audience only, the new owner – theoretically – will be able to add a new integration and receive your tokens.

Last modified on Sep 23, 2024

Webhooks App Store