1"use strict";(self.webpackChunkbackstage_microsite=self.webpackChunkbackstage_microsite||[]).push([["15939"],{840973(e,t,n){n.r(t),n.d(t,{assets:()=>d,contentTitle:()=>a,default:()=>h,frontMatter:()=>s,metadata:()=>i,toc:()=>c});var i=n(989353),r=n(474848),o=n(28453);let s={id:"provider",title:"Bitbucket Authentication Provider",sidebar_label:"Bitbucket",description:"Adding Bitbucket OAuth as an authentication provider in Backstage"},a,d={},c=[{value:"Create an OAuth Consumer in Bitbucket",id:"create-an-oauth-consumer-in-bitbucket",level:2},{value:"Configuration",id:"configuration",level:2},{value:"Optional",id:"optional",level:3},{value:"Resolvers",id:"resolvers",level:3},{value:"Backend Installation",id:"backend-installation",level:2},{value:"Adding the provider to the Backstage frontend",id:"adding-the-provider-to-the-backstage-frontend",level:2}];function l(e){let t={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsxs)(t.p,{children:["The Backstage ",(0,r.jsx)(t.code,{children:"core-plugin-api"})," package comes with a Bitbucket authentication\nprovider that can authenticate users using Bitbucket Cloud. This does ",(0,r.jsx)(t.strong,{children:"NOT"}),"\nwork with Bitbucket Server."]}),"\n",(0,r.jsx)(t.h2,{id:"create-an-oauth-consumer-in-bitbucket",children:"Create an OAuth Consumer in Bitbucket"}),"\n",(0,r.jsx)(t.p,{children:"To add Bitbucket Cloud authentication, you must create an OAuth Consumer."}),"\n",(0,r.jsxs)(t.p,{children:["Go to ",(0,r.jsx)(t.code,{children:"https://bitbucket.org/<your-project-name>/workspace/settings/api"})," ."]}),"\n",(0,r.jsx)(t.p,{children:"Click Add Consumer."}),"\n",(0,r.jsx)(t.p,{children:"Settings for local development:"}),"\n",(0,r.jsxs)(t.ul,{children:["\n",(0,r.jsx)(t.li,{children:"Application name: Backstage (or your custom app name)"}),"\n",(0,r.jsxs)(t.li,{children:["Callback URL: ",(0,r.jsx)(t.code,{children:"http://localhost:7007/api/auth/bitbucket"})]}),"\n",(0,r.jsx)(t.li,{children:"Other are optional"}),"\n",(0,r.jsxs)(t.li,{children:["(IMPORTANT) ",(0,r.jsx)(t.strong,{children:"Permissions: Account - Read, Workspace membership - Read"})]}),"\n"]}),"\n",(0,r.jsx)(t.h2,{id:"configuration",children:"Configuration"}),"\n",(0,r.jsxs)(t.p,{children:["The provider configuration can then be added to your ",(0,r.jsx)(t.code,{children:"app-config.yaml"})," under the\nroot ",(0,r.jsx)(t.code,{children:"auth"})," configuration:"]}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-yaml",children:"auth:\n environment: development\n providers:\n bitbucket:\n development:\n clientId: ${AUTH_BITBUCKET_CLIENT_ID}\n clientSecret: ${AUTH_BITBUCKET_CLIENT_SECRET}\n ## uncomment to set lifespan of user session\n # sessionDuration: { hours: 24 } # supports `ms` library format (e.g. '24h', '2 days'), ISO duration, \"human duration\" as used in code\n signIn:\n resolvers:\n # See https://backstage.io/docs/auth/bitbucket/provider#resolvers for more resolvers\n - resolver: userIdMatchingUserEntityAnnotation\n"})}),"\n",(0,r.jsx)(t.p,{children:"The Bitbucket provider is a structure with two configuration keys:"}),"\n",(0,r.jsxs)(t.ul,{children:["\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.code,{children:"clientId"}
1),": The Key that you generated in Bitbucket, e.g.\n",(0,r.jsx)(t.code,{children:"b59241722e3c3b4816e2"})]}),"\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.code,{children:"clientSecret"}),": The Secret tied to the generated Key."]}),"\n"]}),"\n",(0,r.jsx)(t.h3,{id:"optional",children:"Optional"}),"\n",(0,r.jsxs)(t.ul,{children:["\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.code,{children:"sessionDuration"}),": Lifespan of the user session."]}),"\n"]}),"\n",(0,r.jsx)(t.h3,{id:"resolvers",children:"Resolvers"}),"\n",(0,r.jsx)(t.p,{children:"This provider includes several resolvers out of the box that you can use:"}),"\n",(0,r.jsxs)(t.ul,{children:["\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.code,{children:"emailMatchingUserEntityProfileEmail"}),": Matches the email address from the auth provider with the User entity that has a matching ",(0,r.jsx)(t.code,{children:"spec.profile.email"}),". If no match is found, it will throw a ",(0,r.jsx)(t.code,{children:"NotFoundError"}),"."]}),"\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.code,{children:"emailLocalPartMatchingUserEntityName"}),": Matches the ",(0,r.jsx)(t.a,{href:"https://en.wikipedia.org/wiki/Email_address#Local-part",children:"local part"})," of the email address from the auth provider with the User entity that has a matching ",(0,r.jsx)(t.code,{children:"name"}),". If no match is found, it will throw a ",(0,r.jsx)(t.code,{children:"NotFoundError"}),"."]}),"\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.code,{children:"userIdMatchingUserEntityAnnotation"}),": Matches the ",(0,r.jsx)(t.code,{children:"userId"})," from the auth provider with the User entity that has a matching ",(0,r.jsx)(t.code,{children:"bitbucket.org/user-id"})," annotation. If no match is found, it will throw a ",(0,r.jsx)(t.code,{children:"NotFoundError"}),"."]}),"\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.code,{children:"usernameMatchingUserEntityAnnotation"}),": Matches the ",(0,r.jsx)(t.code,{children:"username"})," from the auth provider with the User entity that has a matching ",(0,r.jsx)(t.code,{children:"bitbucket.org/username"})," annotation. If no match is found, it will throw a ",(0,r.jsx)(t.code,{children:"NotFoundError"}),"."]}),"\n"]}),"\n",(0,r.jsx)(t.admonition,{type:"note",children:(0,r.jsxs)(t.p,{children:["The resolvers will be tried in order but will only be skipped if they throw a ",(0,r.jsx)(t.code,{children:"NotFoundError"}),"."]})}),"\n",(0,r.jsxs)(t.p,{children:["If these resolvers do not fit your needs, you can build a custom resolver; this is covered in the ",(0,r.jsx)(t.a,{href:"/docs/next/auth/identity-resolver#building-custom-resolvers",children:"Building Custom Resolvers"})," section of the Sign-in Identities and Resolvers documentation."]}),"\n",(0,r.jsx)(t.h2,{id:"backend-installation",children:"Backend Installation"}),"\n",(0,r.jsx)(t.p,{children:"To add the provider to the backend, we will first need to install the package by running this command:"}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.code,{className:"language-bash",metastring:'title="from your Backstage root directory"',children:"yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-bitbucket-provider\n"})}),"\n",(0,r.jsx)(t.p,{children:"Then we will need to add this line:"}),"\n",(0,r.jsx)(t.pre,{children:(0,r.jsx)(t.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(import('@backstage/plugin-auth-backend-module-bitbucket-provider'));\n/* highlight-add-end */\n"})}),"\n",(0,r.jsx)(t.h2,{id:"adding-the-provider-to-the-backstage-frontend",children:"Adding the provider to the Backstage frontend"}),"\n",(0,r.jsxs)(t.p,{children:["To add the provider to the frontend, add the ",(0,r.jsx)(t.code,{children:"bitbucketAuthApi"})," reference and\n",(0,r.jsx)(t.code,{children:"SignInPage"})," component as shown in\n",(0,r.jsx)(t.a,{href:"/docs/next/auth/#sign-in-configuration",children:"Adding the provider to the sign-in page"}),"."]})]})}function h(e={}){let{wrapper:t}={...(0,o.R)(),...e.components};return t?(0,r.jsx)(t,{...e,children:(0,r.jsx)(l,{...e})}):l(e)}},28453(e,t,n){n.d(t,{R:()=>s,x:()=>a});var i=n(296540);let r={},o=i.createContext(r);function s(e){let t=i.useContext(o);return i.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function a(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:s(e.components),i.createElement(o.Provider,{value:t},e.children)}},989353(e){e.exports=JSON.parse('{"id":"auth/bitbucket/provider","title":"Bitbucket Authentication Provider","description":"Adding Bitbucket OAuth as an authentication provider in Backstage","source":"@site/../docs/auth/bitbucket/provider.md","
1sourceDirName":"auth/bitbucket","slug":"/auth/bitbucket/provider","permalink":"/docs/next/auth/bitbucket/provider","draft":false,"unlisted":false,"editUrl":"https://github.com/backstage/backstage/edit/master/docs/auth/bitbucket/provider.md","tags":[],"version":"current","frontMatter":{"id":"provider","title":"Bitbucket Authentication Provider","sidebar_label":"Bitbucket","description":"Adding Bitbucket OAuth as an authentication provider in Backstage"},"sidebar":"docs","previous":{"title":"Azure Easy Auth","permalink":"/docs/next/auth/microsoft/easy-auth"},"next":{"title":"Bitbucket Server","permalink":"/docs/next/auth/bitbucketServer/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.