1"use strict";(self.webpackChunkbackstage_microsite=self.webpackChunkbackstage_microsite||[]).push([["15579"],{754515(e,n,t){t.r(n),t.d(n,{assets:()=>s,contentTitle:()=>c,default:()=>h,frontMatter:()=>r,metadata:()=>a,toc:()=>l});var a=t(507594),i=t(474848),o=t(28453);let r={id:"provider",title:"Keycloak Authentication Provider",sidebar_label:"Keycloak",description:"Adding Keycloak as an authentication provider in Backstage"},c,s={},l=[{value:"Create a client on Keycloak",id:"create-a-client-on-keycloak",level:2},{value:"Configuration",id:"configuration",level:2},{value:"Backend installation",id:"backend-installation",level:2},{value:"Synchronizing users and groups",id:"synchronizing-users-and-groups",level:2},{value:"Adding the provider to the Backstage frontend",id:"adding-the-provider-to-the-backstage-frontend",level:2}];function d(e){let n={a:"a",code:"code",h2:"h2",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(n.p,{children:["Backstage can authenticate users using ",(0,i.jsx)(n.a,{href:"https://www.keycloak.org/",children:"Keycloak"}),"\nOpenID Connect. This provider is available through the community-maintained\n",(0,i.jsx)(n.a,{href:"https://github.com/backstage/community-plugins/tree/main/workspaces/keycloak/plugins/auth-backend-module-keycloak",children:(0,i.jsx)(n.code,{children:"@backstage-community/plugin-auth-backend-module-keycloak-provider"})}),"\nmodule."]}),"\n",(0,i.jsx)(n.h2,{id:"create-a-client-on-keycloak",children:"Create a client on Keycloak"}),"\n",(0,i.jsxs)(n.p,{children:["Create an OpenID Connect client with ",(0,i.jsx)(n.strong,{children:"Client authentication"})," enabled and\n",(0,i.jsx)(n.code,{children:"<backend-url>/api/auth/keycloak/handler/frame"})," as a valid redirect URI. See the\n",(0,i.jsx)(n.a,{href:"https://github.com/backstage/community-plugins/tree/main/workspaces/keycloak/plugins/auth-backend-module-keycloak#create-a-client-on-keycloak",children:"module documentation"}),"\nfor the full steps."]}),"\n",(0,i.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,i.jsxs)(n.p,{children:["The provider configuration can then be added to your ",(0,i.jsx)(n.code,{children:"app-config.yaml"})," under\nthe root ",(0,i.jsx)(n.code,{children:"auth"})," configuration:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"auth:\n environment: development\n providers:\n keycloak:\n development:\n clientId: ${AUTH_KEYCLOAK_CLIENT_ID}\n clientSecret: ${AUTH_KEYCLOAK_CLIENT_SECRET}\n baseUrl: ${AUTH_KEYCLOAK_BASE_URL}\n realm: ${AUTH_KEYCLOAK_REALM}\n signIn:\n resolvers:\n # See the module documentation for more resolvers\n - resolver: preferredUsernameMatchingUserEntityName\n"})}),"\n",(0,i.jsx)(n.p,{children:"The Keycloak provider is a structure with these configuration keys:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"clientId"}),": The client ID that you registered on Keycloak, for example\n",(0,i.jsx)(n.code,{children:"backstage"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"clientSecret"}),": The client secret generated for the client in Keycloak."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"baseUrl"}),": The base URL of the Keycloak server, without a trailing\n",(0,i.jsx)(n.code,{children:"/realms/..."})," path, for example ",(0,i.jsx)(n.code,{children:"https://keycloak.example.com"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"realm"}),": The name of the Keycloak realm that Backstage authenticates\nagainst."]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["Optional configuration such as ",(0,i.jsx)(n.code,{children:"additionalScopes"}),", ",(0,i.jsx)(n.code,{children:"postLogoutRedirectUri"}),",\nand ",(0,i.jsx)(n.code,{children:"prompt"})," is described in the\n",(0,i.jsx)(n.a,{href:"https://github.com/backstage/community-plugins/tree/main/workspaces/keycloak/plugins/auth-backend-module-keycloak#configuration",children:"configuration reference"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["Available sign-in resolvers are listed in the\n",(0,i.jsx)(n.a,{href:"https://github.com/backstage/community-plugins/tree/main/workspaces
1/keycloak/plugins/auth-backend-module-keycloak#sign-in-resolvers",children:"module's sign-in resolvers"}),".\nIf none of them fit your needs, see\n",(0,i.jsx)(n.a,{href:"/docs/next/auth/identity-resolver#building-custom-resolvers",children:"Building Custom Resolvers"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"backend-installation",children:"Backend installation"}),"\n",(0,i.jsx)(n.p,{children:"To add the provider to the backend we will first need to install the package\nby running this command:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",metastring:'title="from your Backstage root directory"',children:"yarn --cwd packages/backend add @backstage-community/plugin-auth-backend-module-keycloak-provider\n"})}),"\n",(0,i.jsx)(n.p,{children:"Then we will need to add this line:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",metastring:'title="in packages/backend/src/index.ts"',children:"backend.add(import('@backstage/plugin-auth-backend'));\n/* highlight-add-start */\nbackend.add(\n import('@backstage-community/plugin-auth-backend-module-keycloak-provider'),\n);\n/* highlight-add-end */\n"})}),"\n",(0,i.jsx)(n.h2,{id:"synchronizing-users-and-groups",children:"Synchronizing users and groups"}),"\n",(0,i.jsxs)(n.p,{children:["The sign-in resolvers require a matching User entity to already exist in the\nSoftware Catalog. The recommended way to achieve this is to install the\ncommunity-maintained\n",(0,i.jsx)(n.a,{href:"https://github.com/backstage/community-plugins/tree/main/workspaces/keycloak/plugins/catalog-backend-module-keycloak",children:(0,i.jsx)(n.code,{children:"@backstage-community/plugin-catalog-backend-module-keycloak"})}),"\nplugin, which synchronizes Keycloak users and groups into the catalog on a\nschedule. See\n",(0,i.jsx)(n.a,{href:"/docs/next/integrations/keycloak/org",children:"Keycloak Organizational Data"})," for more\ninformation."]}),"\n",(0,i.jsx)(n.h2,{id:"adding-the-provider-to-the-backstage-frontend",children:"Adding the provider to the Backstage frontend"}),"\n",(0,i.jsxs)(n.p,{children:["Backstage does not ship a built-in auth API for Keycloak, so you need to\ncreate and register a Keycloak auth API reference in your app. The\n",(0,i.jsx)(n.a,{href:"https://github.com/backstage/community-plugins/tree/main/workspaces/keycloak/plugins/auth-backend-module-keycloak#adding-the-provider-to-the-backstage-frontend",children:"module documentation"}),"\ncontains a complete example. Then add the ",(0,i.jsx)(n.code,{children:"SignInPage"})," component as shown in\n",(0,i.jsx)(n.a,{href:"/docs/next/auth/#sign-in-configuration",children:"Adding the provider to the sign-in page"}),"."]})]})}function h(e={}){let{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},28453(e,n,t){t.d(n,{R:()=>r,x:()=>c});var a=t(296540);let i={},o=a.createContext(i);function r(e){let n=a.useContext(o);return a.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:r(e.components),a.createElement(o.Provider,{value:n},e.children)}},507594(e){e.exports=JSON.parse('{"id":"auth/keycloak/provider","title":"Keycloak Authentication Provider","description":"Adding Keycloak as an authentication provider in Backstage","source":"@site/../docs/auth/keycloak/provider.md","sourceDirName":"auth/keycloak","slug":"/auth/keycloak/provider","permalink":"/docs/next/auth/keycloak/provider","draft":false,"unlisted":false,"editUrl":"https://github.com/backstage/backstage/edit/master/docs/auth/keycloak/provider.md","tags":[],"version":"current","frontMatter":{"id":"provider","title":"Keycloak Authentication Provider","sidebar_label":"Keycloak","description":"Adding Keycloak as an authentication provider in Backstage"},"sidebar":"docs","previous":{"title":"Guest","permalink":"/docs/next/auth/guest/provider"},"next":{"title":"Okta","permalink":"/docs/next/auth/okta/provider"}}')}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.