Configuring SSO

Configuring SSO (Single Sign-On)

Piro supports OIDC / OAuth2 identity providers, allowing your team to sign in with their existing Google, Microsoft, Okta, or any standard OIDC-compliant accounts.

SAML 2.0 support is coming in a future release.

---

How it works

Piro implements the Authorization Code Flow with PKCE (S256). No implicit flow, no client-side token exposure.

1. User clicks the provider button on the sign-in page.
2. Piro redirects to the provider's authorization endpoint.
3. After the user authenticates, the provider redirects back to Piro with an authorization code.
4. Piro exchanges the code for an access token, fetches the user's profile from the userinfo endpoint, and upserts the user in the database.
5. A Piro JWT is issued and set as an httpOnly cookie.

---

Admin setup

Go to Settings → SSO (/admin/configuration/sso) and click Add Provider.

Field	Description
Provider ID	A lowercase slug used internally, e.g. google, microsoft. Cannot be changed after creation.
Display Name	Label shown on the sign-in button, e.g. Google.
Authority URL	The base URL of the OIDC provider. Piro fetches {authority}/.well-known/openid-configuration to discover endpoints automatically.
Client ID	Application/client ID from your provider's app registration.
Client Secret	Stored encrypted at rest using ASP.NET Data Protection. Never exposed via the API.
Redirect URI	Copy this value into your provider's Allowed redirect URIs list.
Scopes	Comma-separated. Minimum required: openid, profile, email.
Allowed Email Domains	Optional comma-separated list. When set, only users whose email matches one of these domains can sign in. Leave blank to allow any domain.
Default Role	Role assigned to new users on their first SSO sign-in. Cannot be Owner.
Enabled	Toggle to disable a provider without deleting its configuration.

Click Test Connection to verify that Piro can reach the provider's discovery document before saving.

---

Provider-specific setup guides

Google

1. Open Google Cloud Console → APIs & Services → Credentials.
2. Click Create Credentials → OAuth 2.0 Client ID.
3. Application type: Web application.
4. Add the Piro Redirect URI to Authorized redirect URIs.
5. Copy the Client ID and Client Secret.

Field	Value
Authority URL	https://accounts.google.com
Scopes	openid, profile, email

To restrict sign-in to a specific Google Workspace domain set Allowed Email Domains to yourdomain.com.

---

Microsoft Entra ID (Azure AD)

1. Open Azure Portal → Microsoft Entra ID → App registrations → New registration.
2. Under Redirect URI, add a Web redirect with the Piro Redirect URI.
3. Go to Certificates & secrets → New client secret — copy the value immediately.
4. Copy the Application (client) ID from the Overview page.
5. Use your Directory (tenant) ID in the authority URL below.

Field	Value
Authority URL	https://login.microsoftonline.com/{tenant-id}/v2.0
Scopes	openid, profile, email

Replace {tenant-id} with your Azure AD tenant ID (or use common for multi-tenant).

---

Okta

1. In your Okta Admin console, go to Applications → Create App Integration.
2. Select OIDC - OpenID Connect → Web Application.
3. Add the Piro Redirect URI to Sign-in redirect URIs.
4. Copy Client ID and Client secret.

Field	Value
Authority URL	https://{your-okta-domain}
Scopes	openid, profile, email

---

Auth0

1. In the Auth0 dashboard go to Applications → Create Application → Regular Web Applications.
2. Under Settings → Allowed Callback URLs add the Piro Redirect URI.
3. Copy Domain, Client ID, and Client Secret.

Field	Value
Authority URL	https://{your-auth0-domain}
Scopes	openid, profile, email

---

Generic OIDC provider

Any provider that exposes a /.well-known/openid-configuration discovery document works. Set the Authority URL to the base URL of the provider and Piro will discover all endpoints automatically.

---

Troubleshooting

Issue	Likely cause
"Test Connection" fails	Piro cannot reach the discovery document — check the Authority URL and firewall rules.
"Domain not allowed" error on sign-in	The user's email domain is not in Allowed Email Domains.
User lands back on sign-in with oidc_error=1	State mismatch (expired or reused) — try again.
New user gets wrong role	Update Default Role on the provider config. Existing users' roles are not changed automatically.