https://authress.io/knowledge-base/assets/js/75d77a70.699458b2.js

1"use strict";(self.webpackChunkAuthressKnowledgeBase=self.webpackChunkAuthressKnowledgeBase||[]).push([[3437],{3905:(e,t,n)=>{n.d(t,{Zo:()=>u,kt:()=>h});var r=n(67294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function a(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?i(Object(n),!0).forEach((function(t){o(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):i(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function s(e,t){if(null==e)return{};var n,r,o=function(e,t){if(null==e)return{};var n,r,o={},i=Object.keys(e);for(r=0;r<i.length;r++)n=i[r],t.indexOf(n)>=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r<i.length;r++)n=i[r],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var c=r.createContext({}),l=function(e){var t=r.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},u=function(e){var t=l(e.components);return r.createElement(c.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},d=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,c=e.parentName,u=s(e,["components","mdxType","originalType","parentName"]),d=l(n),h=o,m=d["".concat(c,".").concat(h)]||d[h]||p[h]||i;return n?r.createElement(m,a(a({ref:t},u),{},{components:n})):r.createElement(m,a({ref:t},u))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,a=new Array(i);a[0]=d;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,a[1]=s;for(var l=2;l<i;l++)a[l]=n[l];return r.createElement.apply(null,a)}return r.createElement.apply(null,n)}d.displayName="MDXCreateElement"},42458:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>a,default:()=>p,frontMatter:()=>i,metadata:()=>s,toc:()=>l});var r=n(87462),o=(n(67294),n(3905));const i={sidebar_label:"GitHub Actions OIDC",title:"Access Authress through GitHub Actions",description:"Generate temporary credentials to access Authress from GitHub Actions",image_alt:"GitHub Actions OIDC"},a=void 0,s={unversionedId:"cicd/github/index",id:"cicd/github/index",title:"Access Authress through GitHub Actions",description:"Generate temporary credentials to access Authress from GitHub Actions",source:"@site/docs/50-cicd/01-github/index.md",sourceDirName:"50-cicd/01-github",slug:"/cicd/github/",permalink:"/knowledge-base/docs/cicd/github/",draft:!1,editUrl:"https://gitlab.com/rhosys/authress-public-kb/knowledge-base/-/blob/main/docs/50-cicd/01-github/index.md",tags:[],version:"current",lastUpdatedAt:1772377859,formattedLastUpdatedAt:"Mar 1, 2026",frontMatter:{sidebar_label:"GitHub Actions OIDC",title:"Access Authress through GitHub Actions",description:"Generate temporary credentials to access Authress from GitHub Actions",image_alt:"GitHub Actions OIDC"},sidebar:"tutorialSidebar",previous:{title:"CI/CD Automation",permalink:"/knowledge-base/docs/cicd/"},next:{title:"GitLab Pipelines OIDC",permalink:"/knowledge-base/docs/cicd/gitlab/"}},c={},l=[{value:"Background",id:"background",level:2},{value:"Setup",id:"setup",level:2},{value:"Add GitHub as a trusted provider",id:"add-github-as-a-trusted-provider",level:3},{value:"Enable permissions for your org",id:"enable-permissions-for-your-org",level:3},{value:"Log into Authress in a GitHub Action",id:"log-into-authress-in-a-github-action",level:3}],u={toc:l};function p(e){let{components:t,...i}=e;return(0,o.kt)("wrapper",(0,r.Z)({},u,i,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h2",{id:"background"},"Background"),(0,o.kt)("p",null,"To access Authress securely--updating roles, access records, connections, etc--requires a valid access token. Access tokens can be generated by one of a few different mechanisms. In this guide we'll review how to use the ",(0,o.kt)("inlineCode",{parentName:"p"},"trusted OIDC provider"),". The ",(0,o.kt)("inlineCode",{parentName:"p"},"Trusted OIDC provider")," is the correct option to use when you have an existing system that generates JWTs. If you have an existing Auth provider that your software already trusts, this is the right solution, such as Cognito, Firebase, Auth0, Terraform, GitLab, etc..."),(0,o.kt)("p",null,"Because GitHub can generate its own JWTs, Authress can use those tokens. In this guide we will set up a ",(0,o.kt)("inlineCode",{parentName:"p"},"Trusted OIDC Provider")," from the ",(0,o.kt)("a",{parentName:"p",href:"https://authress.io/app/#/settings?focus=connections"},"Instructions")," in the ",(0,o.kt)("inlineCode",{parentName:"p"},"Connections")," section of the Authress Management Portal."),(0,o.kt)("h2",{id:"setup"},"Setup"),(0,o.kt)("p",null,"To enable ",(0,o.kt)("a",{parentName:"p",href:"https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect"},"GitHub OIDC JWTs")," access to your Authress account, we'll review the steps here."),(0,o.kt)("h3",{id:"add-github-as-a-trusted-provider"},"Add GitHub as a trusted provider"),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},"Log into your Authress account and navigate ",(0,o.kt)("a",{parentName:"li",href:"https://authress.io/app/#/settings?focus=connections"},"Connections")),(0,o.kt)("li",{parentName:"ol"},"Scroll down to ",(0,o.kt)("inlineCode",{parentName:"li"},"OIDC Trusted identities")," and click ",(0,o.kt)("strong",{parentName:"li"},"Add trusted provider"),".")),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"GitHub OIDC Trusted Provider",src:n(78984).Z,width:"881",height:"251"})),(0,o.kt)("ol",{start:3},(0,o.kt)("li",{parentName:"ol"},"Click the button for ",(0,o.kt)("inlineCode",{parentName:"li"},"I don't have access to a token"),". (Normally, you would want to verify your configuration with an actual JWT, however obtaining one from GitHub is a challenge). And then enter the following values:")),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Provider's Issuer URL"),": ",(0,o.kt)("inlineCode",{parentName:"li"},"https://token.actions.githubusercontent.com")),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Provider's Audience"),": ",(0,o.kt)("inlineCode",{parentName:"li"},"https://api.authress.io"))),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Provider JWT configuration",src:n(61348).Z,width:"794",height:"431"})),(0,o.kt)("ol",{start:4},(0,o.kt)("li",{parentName:"ol"},"Click ",(0,o.kt)("strong",{parentName:"li"},"Link provider")," to complete the setup")),(0,o.kt)("h3",{id:"enable-permissions-for-your-org"},"Enable permissions for your org"),(0,o.kt)("p",null,"At this point Authress enables verifying tokens from GitHub, but to prevent unauthorized access, these tokens won't have permissions to change any of your Authress resources. In other words, just because we can prove that a user or entity is who they say they are, that doesn't automatically give them access to protected resources."),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},"Navigate to ",(0,o.kt)("a",{parentName:"li",href:"https://authress.io/app/#/settings?focus=records"},"Access Records"),"."),(0,o.kt)("li",{parentName:"ol"},"Click ",(0,o.kt)("strong",{parentName:"li"},"Create access record"),"."),(0,o.kt)("li",{parentName:"ol"},"Under ",(0,o.kt)("strong",{parentName:"li"},"Users & Groups"),", enter the following User ID that matches your github organization. We want to give your organization (or specifically a single repo access to your Authress account). This user will match. Authress matches the ",(0,o.kt)("inlineCode",{parentName:"li"},"sub")," claim of the incoming JWT. Depending on where your job is running will decide what the ",(0,o.kt)("inlineCode",{parentName:"li"},"User ID")," should be. We'll assume for this example that you want to update Authress from your ",(0,o.kt)("inlineCode",{parentName:"li"},"main")," branch of your git repository. If your GitHub org is called ",(0,o.kt)("inlineCode",{parentName:"li"},"my-org"),", and the repo in that org is called ",(0,o.kt)("inlineCode",{parentName:"li"},"authress-configuration"),", then configuration you want is")),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"User ID"),": ",(0,o.kt)("inlineCode",{parentName:"li"},"repo:my-org/authress-configuration:ref:refs/heads/main"))),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"GitHub access record configuration",src:n(97001).Z,width:"780",height:"654"})),(0,o.kt)("p",null,"If you are calling out to Authress from GitHub from a different ",(0,o.kt)("inlineCode",{parentName:"p"},"branch"),", a specific ",(0,o.kt)("inlineCode",{parentName:"p"},"tag"),", a configured ",(0,o.kt)("inlineCode",{parentName:"p"},"environment"),", then review the ",(0,o.kt)("a",{parentName:"p",href:"https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims"},"GitHub subject claim configuration options"),"."),(0,o.kt)("ol",{start:4},(0,o.kt)("li",{parentName:"ol"},"Click on ",(0,o.kt)("strong",{parentName:"li"},"Statements")," and add the permissions you want to assign to the GitHub Runner. The recommendation here would be to restrict access to only the Authress resources that are necessary. In most cases you'll want to limit the configuration to Authress ",(0,o.kt)("a",{parentName:"li",href:"https://authress.io/app/#/settings?focus=roles"},"Roles"),". For the example here we give it the Authress defined ",(0,o.kt)("inlineCode",{parentName:"li"},"Owner")," role. This specifically grants the capability to create, edit, update, and delete any of the ",(0,o.kt)("inlineCode",{parentName:"li"},"Resources"),". And we specify that it will have access to your Authress account ",(0,o.kt)("inlineCode",{parentName:"li"},"Roles")," as well as all ",(0,o.kt)("inlineCode",{parentName:"li"},"\u2736")," resources. Normally you would not need this second one, but depending on your use case, you may decide this is necessary.")),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"GitHub permissions",src:n(65292).Z,width:"7

172",height:"411"})),(0,o.kt)("ol",{start:5},(0,o.kt)("li",{parentName:"ol"},"Click ",(0,o.kt)("strong",{parentName:"li"},"Create record"),".")),(0,o.kt)("p",null,"Your GitHub action now has access to your Authress account. If you have already configured your GitHub Action to generate a token and call Authress, you are done. If this is the first step you have done, see the next section for setting up your GitHub Action."),(0,o.kt)("h3",{id:"log-into-authress-in-a-github-action"},"Log into Authress in a GitHub Action"),(0,o.kt)("p",null,"Now that your GitHub Action has access to your Authress account, we can go and generate the temporary JWT access token your action will use to update your Authress resources."),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},"In your GitHub Action workflow.yml, add the following top level permissions. This allows your job to use JWTs")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'title="Grant GitHub action permission to generate JWTs"',title:'"Grant',GitHub:!0,action:!0,permission:!0,to:!0,generate:!0,'JWTs"':!0},"permissions:\n  contents: read\n  id-token: write\n")),(0,o.kt)("ol",{start:2},(0,o.kt)("li",{parentName:"ol"},"Then tell GitHub to actually generate a JWT for your workflow, by adding this step to your job:")),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'"Generate the Authress access token from GitHub"','"Generate':!0,the:!0,Authress:!0,access:!0,token:!0,from:!0,'GitHub"':!0},"jobs:\n  job:\n    runs-on: ubuntu-latest\n    steps:\n    - name: Install OIDC Client from Core Package\n      run: npm install @actions/[email protected] @actions/http-cl

1ient\n    - name: Get Id Token\n      uses: actions/github-script@v6\n      id: authress_credentials\n      with:\n        script: |\n          const githubAction = require('@actions/core');\n          const token = await githubAction.getIDToken('https://api.authress.io');\n          githubAction.setSecret(token);\n          githubAction.setOutput('authress-key', token);\n          githubAction.exportVariable('AUTHRESS_KEY', token);\n")),(0,o.kt)("p",null,"And now the ",(0,o.kt)("inlineCode",{parentName:"p"},"AUTHRESS_KEY")," environment variable is now available for use in other toolkits, such as ",(0,o.kt)("a",{parentName:"p",href:"/knowledge-base/docs/cicd/terraform/"},"Terraform")," or directly in one of the ",(0,o.kt)("a",{parentName:"p",href:"https://authress.io/app/#/api"},"Authress SDKs"),"."))}p.isMDXComponent=!0},65292:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/access-record-roles-16421be2e90e0f2eefa041505c8758a0.png"},61348:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/enter-github-openid-611292b012d8faa817830b774578dbbd.png"},97001:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/github-access-record-dabac718cb7ea62eebb6560c2d840c59.png"},78984:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/github-oidc-trusted-provider-8214b5c65d2d19020bb60cc5358ab83c.png"}}]);