Skip to main content

GitHub Actions

Validate tokens from GitHub Actions workflows using OIDC federation.

Integration Guide​

Step 1: Installing the Package​

Install the PrimusSaaS.Identity.Validator package via NuGet:

dotnet add package PrimusSaaS.Identity.Validator

Step 2: Configuring Program.cs​

Register the Primus Identity services and middleware in your Program.cs:

using PrimusSaaS.Identity.Validator;

var builder = WebApplication.CreateBuilder(args);

// Add Primus Identity Validator
builder.Services.AddPrimusIdentity(opts => 
    builder.Configuration.GetSection("PrimusIdentity").Bind(opts));

builder.Services.AddControllers();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

app.Run();

Step 3: Configuring App Settings​

Configure the GitHub provider in your appsettings.json:

{
  "PrimusIdentity": {
    "RequireHttpsMetadata": true,
    "ValidateLifetime": true,
    "ClockSkew": "00:05:00",
    "Issuers": [
      {
        "Name": "GitHub",
        "Type": "GitHub",
        "Issuer": "https://token.actions.githubusercontent.com",
        "Audiences": [ "https://github.com/YOUR_ORG" ]
      }
    ]
  }
}
How to configure GitHub Actions OIDC

Understanding GitHub Actions OIDC​

GitHub Actions can request OIDC tokens for workload identity federation. This allows your API to trust tokens from specific GitHub repositories without storing secrets.

1. Configure Your Workflow​

Add permissions and token request to your GitHub Actions workflow:

name: Deploy
on: push

permissions:
  id-token: write  # Required for OIDC
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Get OIDC Token
        id: get-token
        run: |
          TOKEN=$(curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://github.com/YOUR_ORG" | jq -r '.value')
          echo "token=$TOKEN" >> $GITHUB_OUTPUT
      
      - name: Call Your API
        run: |
          curl -X GET "https://your-api.com/github" \
            -H "Authorization: Bearer ${{ steps.get-token.outputs.token }}"

2. Token Claims​

GitHub OIDC tokens include these claims:

ClaimExampleDescription
isshttps://token.actions.githubusercontent.comIssuer
subrepo:octo-org/octo-repo:ref:refs/heads/mainSubject (repo + ref)
audhttps://github.com/YOUR_ORGYour configured audience
repositoryocto-org/octo-repoRepository name
actoroctocatUser who triggered the workflow
refrefs/heads/mainGit ref

Add authorization policies to restrict access:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("GitHubDeploy", policy =>
        policy.RequireClaim("repository", "your-org/your-repo"));
});

Step 4: Configuring Endpoint​

Create a protected endpoint to test the authentication.

[HttpGet("github")]
[Authorize]
public IActionResult Get()
{
    return Ok(new { 
        validated = true,
        issuer = User.FindFirst("iss")?.Value,
        repository = User.FindFirst("repository")?.Value,
        actor = User.FindFirst("actor")?.Value
    });
}

Step 5: Testing the Endpoint​

Run your GitHub Actions workflow to get a token and test the endpoint.

Alternative: Fluent API Configuration​

You can also configure GitHub using the fluent API:

builder.Services.AddPrimusIdentity(opts =>
{
    opts.UseGitHub(
        audience: "https://github.com/YOUR_ORG"
    );
});

Use Cases​

ScenarioDescription
CI/CD DeploymentAuthenticate GitHub Actions for deployments
Package PublishingValidate tokens from release workflows
Infrastructure ChangesSecure Terraform/Pulumi deployments
API AccessAllow workflows to call your APIs