Authentication

Secure your production services with industry-standard authentication mechanisms. WSO2 Integrator provides declarative auth configuration at the service level.

JWT validation

Protect services by validating JWT tokens from an identity provider:

import ballerina/http;

@http:ServiceConfig {
    auth: [
        {
            jwtValidatorConfig: {
                issuer: "https://auth.example.com",
                audience: "my-integration-api",
                signatureConfig: {
                    jwksConfig: {
                        url: "https://auth.example.com/.well-known/jwks.json",
                        cacheConfig: {
                            capacity: 100,
                            defaultMaxAge: 300
                        }
                    }
                },
                scopeKey: "scp"
            },
            scopes: ["read", "write"]
        }
    ]
}
service /api on new http:Listener(9090) {
    resource function get data(http:Request req) returns json {
        return {message: "Authenticated access"};
    }
}

OAuth 2.0 introspection

Validate opaque tokens by calling the token introspection endpoint:

@http:ServiceConfig {
    auth: [
        {
            oauth2IntrospectionConfig: {
                url: "https://auth.example.com/oauth2/introspect",
                clientConfig: {
                    customHeaders: {"Authorization": "Basic " + encodedCredentials}
                }
            },
            scopes: ["admin"]
        }
    ]
}
service /admin on secureListener { }

Basic authentication

For internal or legacy services:

@http:ServiceConfig {
    auth: [
        {
            fileUserStoreConfig: {},
            scopes: ["admin"]
        }
    ]
}
service /internal on new http:Listener(9091) { }

Configure users in Config.toml:

[[ballerina.auth.users]]
username = "admin"
password = "hashed-password"
scopes = ["admin", "read"]

Mutual TLS (mTLS)

Require client certificates for service-to-service authentication. Before configuring mTLS, set up your keystores and truststores as described in Keystores and truststores.

listener http:Listener mtlsListener = new (9443, {
    secureSocket: {
        key: {
            certFile: "/path/to/server.crt",
            keyFile: "/path/to/server.key"
        },
        mutualSsl: {
            verifyClient: http:REQUIRE,
            cert: "/path/to/ca.crt"
        }
    }
});

Combining authentication methods

Support multiple auth mechanisms on a single service. WSO2 Integrator tries each handler in order:

@http:ServiceConfig {
    auth: [
        {jwtValidatorConfig: {issuer: "https://auth.example.com", ...}},
        {oauth2IntrospectionConfig: {url: "https://auth.example.com/introspect", ...}}
    ]
}
service /api on secureListener { }

Agents on Amazon Bedrock AgentCore Runtime

An agent deployed to Amazon Bedrock AgentCore Runtime doesn't authenticate callers itself. AgentCore Runtime authenticates every invocation before it reaches the container. The agent's http:Listener needs no auth configuration.

By default, the runtime uses IAM. A caller signs the request with AWS Signature Version 4, as the AWS CLI and SDKs do, and its IAM identity must be allowed to invoke the runtime:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "InvokeAgent",
    "Effect": "Allow",
    "Action": "bedrock-agentcore:InvokeAgentRuntime",
    "Resource": [
      "arn:aws:bedrock-agentcore:<region>:<account-id>:runtime/<runtime-id>",
      "arn:aws:bedrock-agentcore:<region>:<account-id>:runtime/<runtime-id>/runtime-endpoint/*"
    ]
  }]
}

A caller can also pass a user ID with --runtime-user-id. That needs bedrock-agentcore:InvokeAgentRuntimeForUser on the same resources. Under IAM authentication the runtime doesn't verify the user ID. Treat it as a label from a trusted caller, not as proof of who the user is. To authenticate end users directly, configure the runtime with a JWT authorizer instead of IAM.

What's next

• SSO configuration — Set up single sign-on using OpenID Connect
• API security and rate limiting — Rate limiting and input validation for your APIs
• Secrets and encryption — Manage credentials securely