Quick Start

This guide walks you through creating a working Nauthera configuration from scratch. By the end you will have issued a real OIDC token using curl.

Before You Begin

Make sure the Nauthera operator is installed in your cluster with PostgreSQL configured via Helm values (and optionally Redis for HA deployments). If not, see the Installation guide.

You will also need the operator's issuer URL — the examples below use https://auth.example.com. Replace this with your actual issuer URL from the Helm value operator.issuerUrl.

Step 1: Create an AuthPolicy

A ClusterAuthPolicy defines the cluster-wide rules for token issuance. Create a basic policy that permits the standard OIDC scopes:

# clusterauthpolicy-basic.yaml
apiVersion: auth.nauthera.io/v1alpha1
kind: ClusterAuthPolicy
metadata:
  name: basic-policy
spec:
  allowedScopes:
    - openid
    - profile
    - email
  tokenSettings:
    accessTokenTTL: 1h
    refreshTokenTTL: 24h
    idTokenTTL: 1h
  claimMappings:
    - claim: email
      fromUserAttribute: email
    - claim: name
      fromUserAttribute: name
    - claim: groups
      fromUserAttribute: groups

Tip: You can also create a namespaced AuthPolicy to override cluster-wide defaults for OidcClients in a specific namespace. See the AuthPolicy reference for details.

kubectl apply -f clusterauthpolicy-basic.yaml

Step 2: Create a Test User

Create a user in the Nauthera user store. The admin CLI runs inside the operator pod:

echo "TestP@ssw0rd!" | kubectl exec -i -n nauthera-system deploy/nauthera-operator -- \
  nauthera-admin user create \
    --email testuser@example.com \
    --name "Test User" \
    --groups developers \
    --password-stdin

See the User Management guide for more details on user provisioning.

Step 3: Create an OidcClient

Register an application by creating an OidcClient in your app namespace. The operator provisions OIDC credentials automatically:

kubectl create namespace my-app-dev

# oidcclient-webapp.yaml
apiVersion: auth.nauthera.io/v1alpha1
kind: OidcClient
metadata:
  name: my-webapp
  namespace: my-app-dev
spec:
  displayName: "My Web App (Dev)"
  redirectUris:
    - "http://localhost:3000/callback"
  scopes:
    - openid
    - profile
    - email

kubectl apply -f oidcclient-webapp.yaml

Step 4: Retrieve Client Credentials

The operator creates a Secret (credentials) and a ConfigMap (endpoint URLs) in the same namespace:

# Check that both resources were created
kubectl get secret my-webapp-oidc-credentials -n my-app-dev
kubectl get configmap my-webapp-oidc-config -n my-app-dev

Retrieve the credentials and endpoint configuration:

# Credentials from the Secret
export CLIENT_ID=$(kubectl get secret my-webapp-oidc-credentials -n my-app-dev \
  -o jsonpath='{.data.client_id}' | base64 -d)
export CLIENT_SECRET=$(kubectl get secret my-webapp-oidc-credentials -n my-app-dev \
  -o jsonpath='{.data.client_secret}' | base64 -d)
 
# Endpoints from the ConfigMap
export ISSUER_URL=$(kubectl get configmap my-webapp-oidc-config -n my-app-dev \
  -o jsonpath='{.data.issuer_url}')
export TOKEN_ENDPOINT=$(kubectl get configmap my-webapp-oidc-config -n my-app-dev \
  -o jsonpath='{.data.token_endpoint}')
 
echo "Client ID:      $CLIENT_ID"
echo "Issuer:         $ISSUER_URL"
echo "Token Endpoint: $TOKEN_ENDPOINT"

Tip: In your real deployments, mount both resources into your Pod using envFrom — see the OidcClient reference for examples. No hardcoded URLs needed.

Step 5: Verify Discovery

Confirm the auth server is running and properly configured:

curl -s https://auth.example.com/.well-known/openid-configuration | jq .

You should see a JSON document listing all supported endpoints, scopes, and algorithms. See the Endpoint Reference for details on each endpoint.

Step 6: Get a Token

Option A: Client Credentials (Machine-to-Machine)

The simplest way to get a token — no user interaction required. For dedicated machine-to-machine use cases, consider using a ServiceAccount instead of an OidcClient — it's purpose-built for workloads and supports automatic credential rotation.

Make sure your OidcClient allows the client_credentials grant type:

# Add client_credentials to the OidcClient spec
spec:
  grantTypes:
    - authorization_code
    - refresh_token
    - client_credentials

Then request a token:

curl -s -X POST https://auth.example.com/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=openid" | jq .

This is the standard flow for web applications. It involves a browser redirect to the login page.

1. Build the authorization URL:

AUTH_URL="https://auth.example.com/oauth2/authorize?\
response_type=code&\
client_id=$CLIENT_ID&\
redirect_uri=http://localhost:3000/callback&\
scope=openid%20profile%20email&\
state=random-state-value"
 
echo "Open in your browser: $AUTH_URL"

2. Open the URL in a browser. You will be redirected to the Nauthera login page. Sign in with the test user credentials (testuser@example.com / TestP@ssw0rd!).

3. After login and consent, the browser redirects to:

http://localhost:3000/callback?code=AUTH_CODE&state=random-state-value

Copy the code parameter from the URL.

4. Exchange the authorization code for tokens:

curl -s -X POST https://auth.example.com/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=http://localhost:3000/callback" | jq .

Step 7: Verify the Token

Decode the access token to inspect its claims:

# Extract and decode the JWT payload (middle segment)
echo "$ACCESS_TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq .

You should see claims like:

{
  "iss": "https://auth.example.com",
  "sub": "user-uuid",
  "aud": "a1b2c3d4-...",
  "exp": 1711234567,
  "iat": 1711230967,
  "email": "testuser@example.com",
  "name": "Test User",
  "groups": ["developers"]
}

You can also verify the token signature using the JWKS endpoint:

curl -s https://auth.example.com/.well-known/jwks.json | jq .

And call the UserInfo endpoint:

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://auth.example.com/oauth2/userinfo | jq .

What's Next

Read the Endpoint Reference for the full list of OAuth2/OIDC endpoints.
Read the AuthPolicy reference to learn about fine-grained scope and claim control.
Read the OidcClient reference to explore PKCE, token exchange, and client authentication methods.
Read the Login Experience guide to customize the login page branding.
Explore the Architecture overview to understand how the operator manages these resources.

PreviousInstallation NextArchitecture

Quick Start

This guide walks you through creating a working Nauthera configuration from scratch. By the end you will have issued a real OIDC token using curl.

Before You Begin

Make sure the Nauthera operator is installed in your cluster with PostgreSQL configured via Helm values (and optionally Redis for HA deployments). If not, see the Installation guide.

You will also need the operator's issuer URL — the examples below use https://auth.example.com. Replace this with your actual issuer URL from the Helm value operator.issuerUrl.

Step 1: Create an AuthPolicy

A ClusterAuthPolicy defines the cluster-wide rules for token issuance. Create a basic policy that permits the standard OIDC scopes:

# clusterauthpolicy-basic.yaml
apiVersion: auth.nauthera.io/v1alpha1
kind: ClusterAuthPolicy
metadata:
  name: basic-policy
spec:
  allowedScopes:
    - openid
    - profile
    - email
  tokenSettings:
    accessTokenTTL: 1h
    refreshTokenTTL: 24h
    idTokenTTL: 1h
  claimMappings:
    - claim: email
      fromUserAttribute: email
    - claim: name
      fromUserAttribute: name
    - claim: groups
      fromUserAttribute: groups

Tip: You can also create a namespaced AuthPolicy to override cluster-wide defaults for OidcClients in a specific namespace. See the AuthPolicy reference for details.

kubectl apply -f clusterauthpolicy-basic.yaml

Step 2: Create a Test User

Create a user in the Nauthera user store. The admin CLI runs inside the operator pod:

echo "TestP@ssw0rd!" | kubectl exec -i -n nauthera-system deploy/nauthera-operator -- \
  nauthera-admin user create \
    --email testuser@example.com \
    --name "Test User" \
    --groups developers \
    --password-stdin

See the User Management guide for more details on user provisioning.

Step 3: Create an OidcClient

Register an application by creating an OidcClient in your app namespace. The operator provisions OIDC credentials automatically:

kubectl create namespace my-app-dev

# oidcclient-webapp.yaml
apiVersion: auth.nauthera.io/v1alpha1
kind: OidcClient
metadata:
  name: my-webapp
  namespace: my-app-dev
spec:
  displayName: "My Web App (Dev)"
  redirectUris:
    - "http://localhost:3000/callback"
  scopes:
    - openid
    - profile
    - email

kubectl apply -f oidcclient-webapp.yaml

Step 4: Retrieve Client Credentials

The operator creates a Secret (credentials) and a ConfigMap (endpoint URLs) in the same namespace:

# Check that both resources were created
kubectl get secret my-webapp-oidc-credentials -n my-app-dev
kubectl get configmap my-webapp-oidc-config -n my-app-dev

Retrieve the credentials and endpoint configuration:

# Credentials from the Secret
export CLIENT_ID=$(kubectl get secret my-webapp-oidc-credentials -n my-app-dev \
  -o jsonpath='{.data.client_id}' | base64 -d)
export CLIENT_SECRET=$(kubectl get secret my-webapp-oidc-credentials -n my-app-dev \
  -o jsonpath='{.data.client_secret}' | base64 -d)
 
# Endpoints from the ConfigMap
export ISSUER_URL=$(kubectl get configmap my-webapp-oidc-config -n my-app-dev \
  -o jsonpath='{.data.issuer_url}')
export TOKEN_ENDPOINT=$(kubectl get configmap my-webapp-oidc-config -n my-app-dev \
  -o jsonpath='{.data.token_endpoint}')
 
echo "Client ID:      $CLIENT_ID"
echo "Issuer:         $ISSUER_URL"
echo "Token Endpoint: $TOKEN_ENDPOINT"

Tip: In your real deployments, mount both resources into your Pod using envFrom — see the OidcClient reference for examples. No hardcoded URLs needed.

Step 5: Verify Discovery

Confirm the auth server is running and properly configured:

curl -s https://auth.example.com/.well-known/openid-configuration | jq .

You should see a JSON document listing all supported endpoints, scopes, and algorithms. See the Endpoint Reference for details on each endpoint.

Step 6: Get a Token

Option A: Client Credentials (Machine-to-Machine)

Make sure your OidcClient allows the client_credentials grant type:

# Add client_credentials to the OidcClient spec
spec:
  grantTypes:
    - authorization_code
    - refresh_token
    - client_credentials

Then request a token:

curl -s -X POST https://auth.example.com/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=openid" | jq .

This is the standard flow for web applications. It involves a browser redirect to the login page.

1. Build the authorization URL:

AUTH_URL="https://auth.example.com/oauth2/authorize?\
response_type=code&\
client_id=$CLIENT_ID&\
redirect_uri=http://localhost:3000/callback&\
scope=openid%20profile%20email&\
state=random-state-value"
 
echo "Open in your browser: $AUTH_URL"

2. Open the URL in a browser. You will be redirected to the Nauthera login page. Sign in with the test user credentials (testuser@example.com / TestP@ssw0rd!).

3. After login and consent, the browser redirects to:

http://localhost:3000/callback?code=AUTH_CODE&state=random-state-value

Copy the code parameter from the URL.

4. Exchange the authorization code for tokens:

curl -s -X POST https://auth.example.com/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=http://localhost:3000/callback" | jq .

Step 7: Verify the Token

Decode the access token to inspect its claims:

# Extract and decode the JWT payload (middle segment)
echo "$ACCESS_TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq .

You should see claims like:

{
  "iss": "https://auth.example.com",
  "sub": "user-uuid",
  "aud": "a1b2c3d4-...",
  "exp": 1711234567,
  "iat": 1711230967,
  "email": "testuser@example.com",
  "name": "Test User",
  "groups": ["developers"]
}

You can also verify the token signature using the JWKS endpoint:

curl -s https://auth.example.com/.well-known/jwks.json | jq .

And call the UserInfo endpoint:

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://auth.example.com/oauth2/userinfo | jq .

What's Next

Read the Endpoint Reference for the full list of OAuth2/OIDC endpoints.
Read the AuthPolicy reference to learn about fine-grained scope and claim control.
Read the OidcClient reference to explore PKCE, token exchange, and client authentication methods.
Read the Login Experience guide to customize the login page branding.
Explore the Architecture overview to understand how the operator manages these resources.

PreviousInstallation NextArchitecture

Quick Start

#Before You Begin

#Step 1: Create an AuthPolicy

#Step 2: Create a Test User

#Step 3: Create an OidcClient

#Step 4: Retrieve Client Credentials

#Step 5: Verify Discovery

#Step 6: Get a Token

#Option A: Client Credentials (Machine-to-Machine)

#Option B: Authorization Code Flow (User Login)

#Step 7: Verify the Token

#What's Next

Quick Start

#Before You Begin

#Step 1: Create an AuthPolicy

#Step 2: Create a Test User

#Step 3: Create an OidcClient

#Step 4: Retrieve Client Credentials

#Step 5: Verify Discovery

#Step 6: Get a Token

#Option A: Client Credentials (Machine-to-Machine)

#Option B: Authorization Code Flow (User Login)

#Step 7: Verify the Token

#What's Next

Before You Begin

Step 1: Create an AuthPolicy

Step 2: Create a Test User

Step 3: Create an OidcClient

Step 4: Retrieve Client Credentials

Step 5: Verify Discovery

Step 6: Get a Token

Option A: Client Credentials (Machine-to-Machine)

Option B: Authorization Code Flow (User Login)

Step 7: Verify the Token

What's Next

Before You Begin

Step 1: Create an AuthPolicy

Step 2: Create a Test User

Step 3: Create an OidcClient

Step 4: Retrieve Client Credentials

Step 5: Verify Discovery

Step 6: Get a Token

Option A: Client Credentials (Machine-to-Machine)

Option B: Authorization Code Flow (User Login)

Step 7: Verify the Token

What's Next