Adding a Sign-In with HF button to your Space

You can enable a built-in sign-in flow in your Space by seamlessly creating and associating anOAuth/OpenID connect app so users can log in with their HF account.

This enables new use cases for your Space. For instance, when combined withPersistent Storage, a generative AI Space could allow users to log in to access their previous generations, only accessible to them.

This guide will take you through the process of integrating aSign-In with HF button into any Space. If you’re seeking a fast and simple method to implement this in aGradio Space, take a look at itsbuilt-in integration.

You can also use the HF OAuth flow to create a “Sign in with HF” flow in any website or App, outside of Spaces.Read our general OAuth page.

Create an OAuth app

All you need to do is addhf_oauth: true to your Space’s metadata inside yourREADME.md file.

Here’s an example of metadata for a Gradio Space:

title:GradioOauthTestemoji:🏆colorFrom:pinkcolorTo:pinksdk:gradiosdk_version:3.40.0python_version:3.10.6app_file:app.pyhf_oauth:true# optional, default duration is 8 hours/480 minutes. Max duration is 30 days/43200 minutes.hf_oauth_expiration_minutes:480# optional, see "Scopes" below. "openid profile" is always included.hf_oauth_scopes:-read-repos-write-repos-manage-repos-inference-api# optional, restrict access to members of specific organizationshf_oauth_authorized_org:ORG_NAMEhf_oauth_authorized_org:-ORG_NAME1-ORG_NAME2

You can check out theconfiguration reference docs for more information.

This will add the followingenvironment variables to your space:

• OAUTH_CLIENT_ID: the client ID of your OAuth app (public)
• OAUTH_CLIENT_SECRET: the client secret of your OAuth app
• OAUTH_SCOPES: scopes accessible by your OAuth app.
• OPENID_PROVIDER_URL: The URL of the OpenID provider. The OpenID metadata will be available at{OPENID_PROVIDER_URL}/.well-known/openid-configuration.

As for any other environment variable, you can use them in your code by usingos.getenv("OAUTH_CLIENT_ID"), for example.

Redirect URLs

You can use any redirect URL you want, as long as it targets your Space.

Note thatSPACE_HOST isavailable as an environment variable.

For example, you can usehttps://{SPACE_HOST}/login/callback as a redirect URI.

Scopes

The following scopes are always included for Spaces:

• openid: Get the ID token in addition to the access token.
• profile: Get the user’s profile information (username, avatar, etc.)

Those scopes are optional and can be added by settinghf_oauth_scopes in your Space’s metadata:

• email: Get the user’s email address.
• read-billing: Know whether the user has a payment method set up.
• read-repos: Get read access to the user’s personal repos.
• contribute-repos: Can create repositories and access those created by this app. Cannot access any other repositories unless additional permissions are granted.
• write-repos: Get write/read access to the user’s personal repos.
• manage-repos: Get full access to the user’s personal repos. Also grants repo creation and deletion.
• inference-api: Get access to theInference Providers, you will be able to make inference requests on behalf of the user.
• jobs: Runjobs
• webhooks: Managewebhooks
• write-discussions: Open discussions and Pull Requests on behalf of the user as well as interact with discussions (including reactions, posting/editing comments, closing discussions, …). To open Pull Requests on private repos, you need to request theread-repos scope as well.

Accessing organization resources

By default, the oauth app does not need to access organization resources.

But some scopes likeread-repos orread-billing apply to organizations as well.

The user can select which organizations to grant access to when authorizing the app. If you require access to a specific organization, you can addorgIds=ORG_ID as a query parameter to the OAuth authorization URL. You have to replaceORG_ID with the organization ID, which is available in theorganizations.sub field of the userinfo response.

Adding the button to your Space

You now have all the information to add a “Sign-in with HF” button to your Space. Some libraries (Python,NodeJS) can help you implement the OpenID/OAuth protocol.

Gradio and huggingface.js also providebuilt-in support, making implementing the Sign-in with HF button a breeze; you can check out the associated guides withgradio and withhuggingface.js.

Basically, you need to:

• Redirect the user tohttps://huggingface.co/oauth/authorize?redirect_uri={REDIRECT_URI}&scope=openid%20profile&client_id={CLIENT_ID}&state={STATE}, whereSTATE is a random string that you will need to verify later.
• Handle the callback on/auth/callback or/login/callback (or your own custom callback URL) and verify thestate parameter.
• Use thecode query parameter to get an access token and id token fromhttps://huggingface.co/oauth/token (POST request withclient_id,code,grant_type=authorization_code andredirect_uri as form data, and withAuthorization: Basic {base64(client_id:client_secret)} as a header).

You should usetarget=_blank on the button to open the sign-in page in a new tab, unless you run the space outside itsiframe. Otherwise, you might encounter issues with cookies on some browsers.

Examples:

• Gradio test app
• HuggingChat (NodeJS/SvelteKit)
• Inference Widgets (Auth.js/SvelteKit), uses theinference-api scope to make inference requests on behalf of the user.
• Client-Side in a Static Space (huggingface.js) - very simple JavaScript example.

JS Code example:

import { oauthLoginUrl, oauthHandleRedirectIfPresent }from"@huggingface/hub";const oauthResult =awaitoauthHandleRedirectIfPresent();if (!oauthResult) {// If the user is not logged in, redirect to the login pagewindow.location.href =awaitoauthLoginUrl();}// You can use oauthResult.accessToken, oauthResult.userInfo among other thingsconsole.log(oauthResult);