Skip to main content

FAQ

Frequently asked questions about SVA OAuth integration.

General Questions​

What is SVA OAuth?​

SVA OAuth is a secure, privacy-first OAuth 2.0 provider that enables applications to authenticate users and access their identity data through a zero-knowledge architecture.

How is SVA OAuth different from other OAuth providers?​

SVA OAuth delivers user identity claims directly in a cryptographically signed JWT, eliminating the need for inefficient API calls to a /userinfo endpoint. It also uses a zero-knowledge architecture where user data remains encrypted until decrypted client-side.

Do I need to call a /userinfo endpoint?​

No! SVA OAuth delivers user data directly in the data_token JWT. You can decode user claims directly from the token without making any API calls.

Installation​

How do I install sva-oauth-client?​

pip install sva-oauth-client

What are the requirements?​

  • Python 3.8+
  • Django 3.2+
  • Django Sessions (for token storage)

Configuration​

Where do I get my OAuth credentials?​

Contact your SVA provider administrator or visit the developer portal to register your application and obtain:

  • Client ID
  • Client Secret
  • Data Token Secret

What is the Data Token Secret?​

The Data Token Secret is used to verify the signature of the data_token JWT. It must match the secret configured in your SVA provider.

Can I use different scopes for different views?​

Yes! You can request different scopes dynamically:

client = SVAOAuthClient(..., scopes='openid email profile username')

Authentication​

How do I protect a view?​

Use the @sva_oauth_required decorator:

@sva_oauth_required
def my_view(request):
    claims = get_sva_claims(request)
    return render(request, 'template.html', {'claims': claims})

How do I require specific identity blocks?​

Use the @sva_blocks_required decorator:

@sva_blocks_required('email', 'name', 'phone')
def profile_view(request):
    claims = get_sva_claims(request)
    # email, name, phone are guaranteed to exist
    return render(request, 'profile.html', {'claims': claims})

What happens if a user hasn't approved required blocks?​

The user will be redirected to login with an error message prompting them to approve the missing blocks.

Tokens​

How long do tokens last?​

  • Access tokens: 1 hour (default)
  • Refresh tokens: 30 days (default)
  • Data tokens: 5 minutes (default)

Do I need to manually refresh tokens?​

No! The TokenRefreshMiddleware automatically refreshes tokens before they expire.

What if a token expires?​

If a token expires, the user will be automatically logged out and redirected to login.

Security​

Is PKCE enabled?​

Yes! PKCE is automatically enabled and handled by the package.

How is CSRF protection implemented?​

CSRF protection is implemented using the state parameter, which is automatically generated and verified by the package.

Are tokens stored securely?​

Yes! Tokens are stored in Django session (server-side) with HttpOnly cookies, preventing JavaScript access.

Data Tokens​

What is a data token?​

A data token is a cryptographically signed JWT that contains user identity claims (blocks). It's included in the token exchange response.

How do I access user data from the data token?​

Use the get_sva_claims() function:

from sva_oauth_client.utils import get_sva_claims

claims = get_sva_claims(request)
email = claims.get('email')
name = claims.get('name')

Why do data tokens expire so quickly (5 minutes)?​

Data tokens expire quickly to limit exposure. If you need fresh data, the user can re-authenticate.

Identity Blocks​

What identity blocks are available?​

Common blocks include:

  • email - Email address
  • name - Full name
  • username - Username
  • phone - Phone number
  • address - Address information
  • And many more...

See the Identity Blocks guide for the complete list.

Can users deny specific blocks?​

Yes! Users can approve or deny individual blocks on the consent screen.

What happens if a block is missing?​

If a required block is missing (when using @sva_blocks_required), the user will be redirected to login with an error message.

Troubleshooting​

I'm getting "redirect_uri_mismatch" error​

Ensure SVA_OAUTH_REDIRECT_URI exactly matches the redirect URI registered in your OAuth app (including protocol, domain, port, and path).

I'm getting "invalid_client" error​

Verify that SVA_OAUTH_CLIENT_ID and SVA_OAUTH_CLIENT_SECRET are correct.

I'm getting "Invalid data token" error​

Ensure SVA_DATA_TOKEN_SECRET matches the secret configured in your SVA provider.

Tokens are not refreshing automatically​

Ensure TokenRefreshMiddleware is in your MIDDLEWARE list and comes after SessionMiddleware.

Best Practices​

Should I store tokens in the database?​

No! Tokens should be stored in Django session (server-side). The package handles this automatically.

Should I expose tokens to the client?​

No! Never send tokens to the client-side. They should remain in server-side session only.

How do I handle token errors?​

Use try/except blocks:

from sva_oauth_client.utils import get_sva_claims
from sva_oauth_client.client import SVATokenError

try:
    claims = get_sva_claims(request)
except SVATokenError:
    # Handle error
    pass

Support​

Where can I get help?​

How do I report a bug?​

Report bugs on the GitHub repository or contact support.

Next Steps​