Single Sign-On with OpenID Connect

To help fit Prodigy into your existing organization, we’ve added support for Single Sign-On (SSO) following the OpenID Connect (OIDC) protocol. Prodigy will act as an OIDC Client that can connect to whichever OIDC Provider your organization uses (e.g. Auth0, Okta, Google, Microsoft Entra, etc.)

Installation

The Prodigy OIDC plugin is a feature only available with the Prodigy Company License. If you have a Company License, ensure you have the company extra for Prodigy installed:

python -mpip installprodigy[company]--extra-index-urlhttps://XXXX-XXXX-XXXX-XXXX@download.prodi.gy

Alternatively, you can install the prodigy-company-plugins package explicitly. This is equivalent to installing the [company] extra.

python -mpip installprodigy-company-plugins--extra-index-urlhttps://XXXX-XXXX-XXXX-XXXX@download.prodi.gy

Using Auth0 as an OIDC Provider

In this guide we’ll focus on authenticating annotators to Prodigy with Auth0 but the same steps can be followed with any OIDC provider. This plugin has been tested with Auth0, Microsoft Entra, and Google Identity.

Create an Auth0 Application

Once you’ve created your user account in Auth0, the first step is to create an application in Auth0 Dashboard. The application in Auth0 Dashboard is where you configure the authentication for the Prodigy web app. It shouldn’t take more than 10 minutes. You can find a step by step tutorial on how to create an application in Auth0 docs here.

At the end you should get a page like this with Config values you’ll use to setup Prodigy.

Set Prodigy as an Allowed Callback URL

You can configure a custom route for the Prodigy Auth Callback handler to be served at but, by default, it will be served at /login/callback

When running Prodigy locally with the default settings, it will be served at http://localhost:8080, so for testing we need to add http://localhost:8080/login/callback to the list of Auth0 Allowed Callback URLs.

Deploying Prodigy with HTTPS

When your local testing is complete and it’s time to deploy the Prodigy server on a public, secured domain, the PRODIGY_DEPLOYED_URL setting can be set as the base URL the OIDC plugin will build all its redirect URLs off of.

For Example, if a Prodigy NER Manual Annotation server has been deployed at https://my-prodigy-ner-server.my-domain.com, set this environment variable like below:

PRODIGY_DEPLOYED_URL="https://my-prodigy-ner-server.my-domain.com"

And now, Auth0 needs to be updated to know about this deployed URL. The login callback URL is the base URL combined with the /login path. So let’s add https://my-prodigy-ner-server.my-domain.com/login/callback to the list of allowed callback URLs in Auth0.

Tip for multiple annotation servers

Some OIDC Providers (including Auth0) will allow you to configure an allowed callback URL with a wildcard domain. If you’re deploying multiple annotation servers behind the same domain, you can configure a wildcard domain in the application portal for your provider, e.g. https://*.my-domain.com/login/callback. You can then set up multiple annotation servers which will pass this rule:

Annotation server 1
PRODIGY_DEPLOYED_URL="https://my-prodigy-ner-server.my-domain.com"

Annotation server 2
PRODIGY_DEPLOYED_URL="https://my-prodigy-textcat-manual-server.my-domain.com"

Configuring Prodigy

Once you have the prodigy-company-plugins package installed, configuring OIDC auth is as simple as setting a few environment variables. To enable the company auth plugin, you explicitly need to set the PRODIGY_OIDC_AUTH_ENABLED variable.

Development tip

If you’re working on a new custom recipe and want to skip auth while you’re developing, just remove the PRODIGY_OIDC_AUTH_ENABLED Environment variable or set it to some falsey value.

PRODIGY_OIDC_AUTH_ENABLED="0"

Prodigy utilizes OpenID Connect Discovery to provide all the endpoints and configuration it will use to authenticate annotators.

Auth0 provides a standard OIDC Discovery endpoint at https://YOUR_APP_DOMAIN/.well-known/openid-configuration , where YOUR_APP_DOMAIN can be found in your Application’s Basic Information under Settings. Other than that, you need to provide your Client ID and Client Secret which you can copy from your Auth0 application dashboard

PRODIGY_OIDC_AUTH_ENABLED="1"
PRODIGY_OIDC_DISCOVERY_URL="https://YOUR_APP_DOMAIN/.well-known/openid-configuration"
PRODIGY_OIDC_CLIENT_ID="YOUR_AUTH0_CLIENT_ID"
PRODIGY_OIDC_CLIENT_SECRET="YOUR_AUTH0_CLIENT_SECRET"

All Configuratable Auth Settings

The OIDC Plugin lets you set any of the following config values.

Variable	Description
`PRODIGY_OIDC_AUTH_ENABLED`	Required. Boolean Flag to enable OIDC company Authentication. Remove or set to a falsey value to skip Auth
`PRODIGY_OIDC_DISCOVERY_URL`	Required. URL pointing to an OpenID Connect Configuration endpoint.
`PRODIGY_OIDC_CLIENT_ID`	Required. The unique Client ID (sometimes called Application ID) of your OpenID Connect Provider.
`PRODIGY_OIDC_CLIENT_SECRET`	Required. A valid Client Secret configured for your specific Client ID.
`PRODIGY_OIDC_AUDIENCE`	The audience to authenticate and verify ID tokens against. This defaults to the Client ID but some providers will require a different audience.
`PRODIGY_OIDC_REQUIRED_SCOPES`	The scopes the user will be asked to give on first login. Defaults to `openid profile email`. Minimally requires `openid profile` for authentication to work. `email` is required for authorization by email domain/address with `PRODIGY_OIDC_ALLOWED_EMAILS`
`PRODIGY_OIDC_ALLOWED_EMAILS`	A list of emails or email domains to restrict access to. e.g. `test@test.com *@yourdomain.com`.
`PRODIGY_OIDC_LOGOUT_PATH`	The OpenID Connect Protocol defines an “end_session_endpoint” which will logout a user. Not all providers will have this endpoint listed (e.g. it’s missing from the Auth0 config). You can customize this logout path if your provider doesn’t return one from the OIDC config. Defaults to `/oidc/logout`.
`PRODIGY_LOGIN_PATH`	The path for the login endpoint on the Prodigy server. User’s are redirected if they aren’t authenticated and this endpoint takes care of redirecting to the configured OIDC provider. Defaults to `/login`.
`PRODIGY_LOGIN_CALLBACK_PATH`	The path for the login redirect endpoint on the Prodigy server. This path informs what you’ll need to enter in your Provider app config in the “Allowed Callback URLs” config area. Defaults to `/login/callback`.
`PRODIGY_LOGOUT_PATH`	The path for the logout endpoint on the Prodigy server. Clears the Auth related cookies before redirecting to the OIDC Logout route if one is provided
`PRODIGY_DEPLOYED_URL`	The base URL the Prodigy server is deployed at. This will be the base URL which all the auth calls are redirected back to.

Starting Prodigy with Auth0 Authentication

The Prodigy OIDC Auth Plugin is built on top of the existing Prodigy application so you can start any annotation recipe you’d like normally.

When you start the annotation server, Prodigy will confirm OIDC Auth is configured in the console (with more details at the verbose logging level) before the server is started.

Recipe command

prodigyner.manualner_news_headlinesblank:en./news_headlines.jsonl--label PERSON,ORG,PRODUCT,LOCATIONℹ Prodigy Company Auth Enabled✨ Starting the web server at http://localhost:8080 ...
Open the app in your browser and start annotating!

Now if we try to start annotating by visiting http://localhost:8080, we’ll be redirected to login with the configured Auth0 application.

By default, Auth0 allows registration of new users for personal applications. So we click “Continue with Google” and sign in to this app with a personal Google Account. Prodigy provides the ?redirect_uri parameter to Auth0 based on what we configured earlier as the login callback URL (by default http://localhost:8080/login/callback).

After signing in with Google, we get redirected to the login callback URL, Prodigy saves some httponly cookies for the ID and Access Tokens provided by Auth0’s token endpoint and each subsequent HTTP request in Prodigy validates the user’s ID Token against the publicly available RS256 JWKs from Auth0. Once the token expires, the cookie is cleared and the user will be asked to login with Auth0 again.

Finally, after the Auth0 login is completed and we’ve saved the authentication cookies, the annotator is redirected to the main Prodigy app at http://localhost:8080?session={YOUR_AUTH0_SUB}. If you’ve never used the Named Multi-User Sessions in Prodigy before, this ?session parameter is what Prodigy uses to deterimine which tasks to route to which annotators depending on your feed_overlap, annotations_per_task settings and your configured task_router.

Each annotation the logged in user makes will now be tagged with their ID provided from Auth0 and can easily be traced back to this user.

Annotate with Prodigy as a known annotator

After logging in with Auth0, an httponly cookie is saved with the user’s ID Token. Visiting the base Prodigy Annotation URL at http://localhost:8080/ will redirect the User to their session specific annotation URI: http://localhost:8080/?session={YOUR_AUTH0_SUB}. The user can now annotate normally.

Restrict authorized annotators by email

Fine-grained control of Authorization can usually be controlled at the OIDC Provider level by restricting an application to a specific organization. If you just want to restrict access based on a user’s email/email domain you can use the PRODIGY_OIDC_ALLOWED_EMAILS setting. The setting accepts a space-separated list of exact or wildcard emails to allow access to.

PRODIGY_OIDC_ALLOWED_EMAILS="*@my_company.com annotator1@gmail.com annotator2@outlook.com"

As an example, the config above would allow any employee of my_company.com along with 2 annotator’s on contract to access Prodigy. Any other logins with invalid emails will get through the Auth0 login step, but will be met with an error when they are redirected back to Prodigy.