SSO (OIDC + SAML + LDAP)

Overview

The SSO service manages OIDC and SAML 2.0 enterprise connections, domain-based enforcement, JIT provisioning, and sessions. It also exposes the current LDAP direct-bind preview; that preview is not a general LDAP directory integration and has the limitations documented below.

conn, err := client.SSO.CreateConnection(ctx, grantex.CreateSsoConnectionParams{
    Name:            "Okta Production",
    Protocol:        "oidc",
    IssuerURL:       "https://mycompany.okta.com",
    ClientID:        "your-client-id",
    ClientSecret:    "your-client-secret",
    Domains:         []string{"mycompany.com"},
    JitProvisioning: true,
})

Enterprise SSO Connections

Create Connection

Create a new SSO identity provider connection. You can create multiple connections for different domains or providers.

conn, err := client.SSO.CreateConnection(ctx, grantex.CreateSsoConnectionParams{
    Name:            "Okta Production",
    Protocol:        "oidc",
    IssuerURL:       "https://mycompany.okta.com",
    ClientID:        "your-okta-client-id",
    ClientSecret:    "your-okta-client-secret",
    Domains:         []string{"mycompany.com", "mycompany.org"},
    JitProvisioning: true,
    DefaultRole:     "member",
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("ID: %s\n", conn.ID)                    // sso_conn_01HX...
fmt.Printf("Name: %s\n", conn.Name)                // Okta Production
fmt.Printf("Protocol: %s\n", conn.Protocol)        // oidc
fmt.Printf("Status: %s\n", conn.Status)            // active
fmt.Printf("Domains: %v\n", conn.Domains)          // [mycompany.com mycompany.org]
fmt.Printf("JIT: %v\n", conn.JitProvisioning)      // true
fmt.Printf("Created: %s\n", conn.CreatedAt)        // 2026-03-29T12:00:00Z

SAML example

samlConn, err := client.SSO.CreateConnection(ctx, grantex.CreateSsoConnectionParams{
    Name:                        "Azure AD SAML",
    Protocol:                    "saml",
    MetadataURL:                 "https://login.microsoftonline.com/.../federationmetadata.xml",
    AssertionConsumerServiceURL: "https://yourapp.com/sso/saml/callback",
    EntityID:                    "https://yourapp.com/saml/metadata",
    Domains:                     []string{"contoso.com"},
    JitProvisioning:             true,
    AttributeMapping: map[string]string{
        "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        "name":  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/displayname",
    },
})

`CreateSsoConnectionParams`

Field	Type	Required	Description
`Name`	`string`	Yes	A human-readable name for this connection.
`Protocol`	`string`	Yes	`"oidc"`, `"saml"`, or `"ldap"`.
`IssuerURL`	`string`	OIDC only	The OIDC issuer URL.
`ClientID`	`string`	OIDC only	OAuth 2.0 client ID from your IdP.
`ClientSecret`	`string`	OIDC only	OAuth 2.0 client secret from your IdP.
`MetadataURL`	`string`	SAML only	The SAML metadata URL.
`AssertionConsumerServiceURL`	`string`	SAML only	The SAML ACS URL.
`EntityID`	`string`	SAML only	The SAML service provider entity ID.
`Domains`	`[]string`	No	Email domains to associate with this connection.
`JitProvisioning`	`bool`	No	Enable just-in-time user provisioning.
`DefaultRole`	`string`	No	Default role for JIT-provisioned users.
`AttributeMapping`	`map[string]string`	No	Custom attribute mapping for SAML assertions.

`SsoConnection`

Field	Type	Description
`ID`	`string`	Unique connection identifier.
`Name`	`string`	The connection display name.
`Protocol`	`string`	`"oidc"`, `"saml"`, or `"ldap"`.
`Status`	`string`	`"active"`, `"inactive"`, or `"error"`.
`Domains`	`[]string`	Associated email domains.
`JitProvisioning`	`bool`	Whether JIT provisioning is enabled.
`CreatedAt`	`string`	ISO 8601 creation timestamp.
`UpdatedAt`	`string`	ISO 8601 last-updated timestamp.

Note: The ClientSecret is never returned in responses. It is stored securely on the server.

List Connections

List all SSO connections for your organization.

resp, err := client.SSO.ListConnections(ctx)
if err != nil {
    log.Fatal(err)
}

for _, conn := range resp.Connections {
    fmt.Printf("%s (%s) - %s\n", conn.Name, conn.Protocol, conn.Status)
    fmt.Printf("  Domains: %v\n", conn.Domains)
}

Get Connection

Retrieve a single SSO connection by ID.

conn, err := client.SSO.GetConnection(ctx, "sso_conn_01HX...")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Name: %s\n", conn.Name)         // Okta Production
fmt.Printf("Protocol: %s\n", conn.Protocol) // oidc
fmt.Printf("Status: %s\n", conn.Status)     // active

Update Connection

Update an existing SSO connection.

updated, err := client.SSO.UpdateConnection(ctx, "sso_conn_01HX...", grantex.UpdateSsoConnectionParams{
    Name:            "Okta Production (updated)",
    JitProvisioning: grantex.Bool(false),
    Domains:         []string{"mycompany.com", "mycompany.org", "subsidiary.com"},
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Name: %s\n", updated.Name)      // Okta Production (updated)
fmt.Printf("Domains: %v\n", updated.Domains) // [mycompany.com mycompany.org subsidiary.com]

`UpdateSsoConnectionParams`

Field	Type	Description
`Name`	`string`	Updated display name.
`Domains`	`[]string`	Updated list of associated email domains.
`JitProvisioning`	`*bool`	Enable or disable JIT provisioning.
`DefaultRole`	`string`	Updated default role for JIT-provisioned users.
`AttributeMapping`	`map[string]string`	Updated SAML attribute mapping.

Delete Connection

Delete an SSO connection. Users associated with this connection will no longer be able to log in via SSO.

err := client.SSO.DeleteConnection(ctx, "sso_conn_01HX...")
if err != nil {
    log.Fatal(err)
}
// Connection is removed

Warning: Deleting a connection immediately disables SSO login for all users routed through it. Ensure you have an alternative authentication method configured before removing a connection.

Test Connection

Test an SSO connection to verify that the IdP configuration is correct and reachable.

test, err := client.SSO.TestConnection(ctx, "sso_conn_01HX...")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Success: %v\n", test.Success)           // true
fmt.Printf("Message: %s\n", test.Message)            // Connection verified successfully
fmt.Printf("Response time: %dms\n", test.ResponseTime) // 142

`SsoTestResult`

Field	Type	Description
`Success`	`bool`	Whether the connection test passed.
`Message`	`string`	Human-readable result message.
`ResponseTime`	`int`	IdP response time in milliseconds.

Enforcement

Set Enforcement

Enforce SSO login for your organization. When enabled, all members must authenticate through an SSO connection.

enforcement, err := client.SSO.SetEnforcement(ctx, grantex.SsoEnforcementParams{
    Enforce: true,
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Enforced: %v\n", enforcement.Enforce)       // true
fmt.Printf("Developer: %s\n", enforcement.DeveloperID)

`SsoEnforcementParams`

Field	Type	Required	Description
`Enforce`	`bool`	Yes	Whether SSO login is enforced for all members.

`SsoEnforcementResponse`

Field	Type	Description
`Enforce`	`bool`	Whether SSO enforcement is active.
`DeveloperID`	`string`	Organization/developer ID updated by the request.

Session Management

List Sessions

List active SSO sessions for your organization.

sessions, err := client.SSO.ListSessions(ctx)
if err != nil {
    log.Fatal(err)
}

for _, s := range sessions.Sessions {
    fmt.Printf("%s - %s - expires %s\n", s.Email, s.ConnectionID, s.ExpiresAt)
}

`SsoSession`

Field	Type	Description
`ID`	`string`	Session identifier.
`DeveloperID`	`string`	Organization/developer that owns the session.
`Email`	`string`	The user’s email address.
`ConnectionID`	`string`	The SSO connection used for this session.
`CreatedAt`	`string`	ISO 8601 session creation timestamp.
`ExpiresAt`	`string`	ISO 8601 session expiration timestamp.

Revoke Session

Revoke an active SSO session, forcing the user to re-authenticate.

err := client.SSO.RevokeSession(ctx, "sso_sess_01HX...")
if err != nil {
    log.Fatal(err)
}
// Session is revoked

Get the SSO authorization URL for an organization, with an optional email-domain hint used to select a configured connection.

login, err := client.SSO.GetLoginURL(ctx, "org_01HXYZ...", "mycompany.com")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Redirect to: %s\n", login.AuthorizeURL)

Parameters

Parameter	Type	Required	Description
`org`	`string`	Yes	Organization/developer ID that owns the SSO connections.
`domain`	`string`	No	Optional email domain used to select a connection.

`SsoLoginResponse` (enterprise)

Field	Type	Description
`AuthorizeURL`	`string`	The full authorization URL. Redirect the user here.

Handle OIDC Callback

Handle the callback from an OIDC identity provider. Exchanges the authorization code for user information and provisions the user if JIT is enabled.

result, err := client.SSO.HandleOidcCallback(ctx, grantex.SsoOidcCallbackParams{
    Code:        "oidc_auth_code",
    State:       "csrf_state",
    RedirectURI: "https://yourapp.com/sso/callback", // optional
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Email: %s\n", *result.Email)              // alice@mycompany.com
fmt.Printf("Name: %s\n", *result.Name)                // Alice Smith
fmt.Printf("Subject: %s\n", *result.Sub)              // okta|abc123
fmt.Printf("Developer ID: %s\n", result.DeveloperID)  // dev_01HXYZ...
fmt.Printf("Session: %s\n", result.SessionID)
fmt.Printf("Scopes: %v\n", result.MappedScopes)

`SsoOidcCallbackParams`

Field	Type	Required	Description
`Code`	`string`	Yes	The authorization code from the OIDC callback.
`State`	`string`	Yes	The state parameter for CSRF protection.
`RedirectURI`	`string`	No	Redirect URI used during the authorization request. Serialized as `redirect_uri`.

`SsoCallbackResult`

Field	Type	Description
`Email`	`*string`	The user’s email address from the IdP.
`Name`	`*string`	The user’s display name from the IdP.
`Sub`	`*string`	The user’s subject identifier from the IdP.
`Groups`	`[]string`	Groups returned by the identity provider.
`MappedScopes`	`[]string`	Scopes produced by group/default-scope mapping.
`PrincipalID`	`*string`	JIT-provisioned or matched principal ID, when available.
`DeveloperID`	`string`	The Grantex developer ID.
`SessionID`	`string`	Created SSO session ID.
`ExpiresAt`	`string`	Session expiration timestamp.

Handle SAML Callback

Handle the callback from a SAML 2.0 identity provider. Validates the SAML assertion and provisions the user if JIT is enabled.

result, err := client.SSO.HandleSamlCallback(ctx, grantex.SsoSamlCallbackParams{
    SAMLResponse: samlResponseValue,
    RelayState:   relayStateValue,
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Email: %s\n", *result.Email)              // bob@contoso.com
fmt.Printf("Name: %s\n", *result.Name)                // Bob Jones
fmt.Printf("Developer ID: %s\n", result.DeveloperID)  // dev_01HXYZ...
fmt.Printf("Session: %s\n", result.SessionID)
fmt.Printf("Scopes: %v\n", result.MappedScopes)

`SsoSamlCallbackParams`

Field	Type	Required	Description
`SAMLResponse`	`string`	Yes	The base64-encoded SAML response from the IdP.
`RelayState`	`string`	No	The RelayState parameter from the SAML callback.

Returns the same SsoCallbackResult as HandleOidcCallback().

Handle LDAP Callback

Authenticate a user with the LDAP direct-bind preview. Unlike OIDC and SAML, credentials are submitted directly. The built-in client binds a service account, constructs a user DN from LdapSearchFilter plus LdapSearchBase, and binds that DN with the submitted password. It does not search entries, read attributes, or retrieve group memberships.

result, err := client.SSO.HandleLdapCallback(ctx, grantex.SsoLdapCallbackParams{
    Username:     "alice",
    Password:     "user-password",
    ConnectionID: "sso_conn_03HX...",
    Org:          "org_01HXYZ...",
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Groups: %v\n", result.Groups)              // []
fmt.Printf("Mapped scopes: %v\n", result.MappedScopes) // default scopes only
fmt.Printf("Developer ID: %s\n", result.DeveloperID)   // dev_01HXYZ...
fmt.Printf("Session: %s\n", result.SessionID)          // ssosess_01HXYZ...

`SsoLdapCallbackParams`

Field	Type	Required	Description
`Username`	`string`	Yes	Username interpolated into the configured filter to construct the user DN; the built-in preview does not search.
`Password`	`string`	Yes	The user’s LDAP password for bind authentication.
`ConnectionID`	`string`	Yes	The SSO connection ID for the LDAP directory.
`Org`	`string`	Yes	Organization/developer ID that owns the LDAP connection.

Returns SsoCallbackResult. With the built-in LDAP client, Groups is empty, Name and Email are absent, and MappedScopes therefore contains only configured default scopes.

Note: LDAP credentials are never stored by Grantex. They are used only for the bind operations and discarded after authentication. LDAP search, attribute retrieval, group lookup/mapping, and broad provider compatibility are not supported by the built-in preview client.

Full Enterprise SSO Flow Example

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/mishrasanjeev/grantex-go"
)

func main() {
    ctx := context.Background()
    client := grantex.NewClient(os.Getenv("GRANTEX_API_KEY"))

    // Step 1: Create SSO connections (one-time setup)
    _, err := client.SSO.CreateConnection(ctx, grantex.CreateSsoConnectionParams{
        Name:            "Okta Production",
        Protocol:        "oidc",
        IssuerURL:       os.Getenv("OKTA_ISSUER_URL"),
        ClientID:        os.Getenv("OKTA_CLIENT_ID"),
        ClientSecret:    os.Getenv("OKTA_CLIENT_SECRET"),
        Domains:         []string{"mycompany.com"},
        JitProvisioning: true,
        DefaultRole:     "member",
    })
    if err != nil {
        log.Fatal(err)
    }

    _, err = client.SSO.CreateConnection(ctx, grantex.CreateSsoConnectionParams{
        Name:                        "Azure AD SAML",
        Protocol:                    "saml",
        MetadataURL:                 os.Getenv("AZURE_METADATA_URL"),
        AssertionConsumerServiceURL: "https://yourapp.com/sso/saml/callback",
        EntityID:                    "https://yourapp.com/saml/metadata",
        Domains:                     []string{"contoso.com"},
        JitProvisioning:             true,
    })
    if err != nil {
        log.Fatal(err)
    }

    // Step 2: Enforce SSO for the organization
    _, err = client.SSO.SetEnforcement(ctx, grantex.SsoEnforcementParams{
        Enforce: true,
    })
    if err != nil {
        log.Fatal(err)
    }

    // Step 3: Redirect user to SSO login based on email domain
    http.HandleFunc("/sso/login", func(w http.ResponseWriter, r *http.Request) {
        domain := r.URL.Query().Get("domain")
        login, err := client.SSO.GetLoginURL(ctx, "org_01HXYZ...", domain)
        if err != nil {
            http.Error(w, err.Error(), 500)
            return
        }
        http.Redirect(w, r, login.AuthorizeURL, http.StatusFound)
    })

    // Step 4a: Handle OIDC callback
    http.HandleFunc("/sso/callback", func(w http.ResponseWriter, r *http.Request) {
        result, err := client.SSO.HandleOidcCallback(ctx, grantex.SsoOidcCallbackParams{
            Code:        r.URL.Query().Get("code"),
            State:       r.URL.Query().Get("state"),
            RedirectURI: "https://yourapp.com/sso/callback",
        })
        if err != nil {
            http.Error(w, err.Error(), 500)
            return
        }

        fmt.Printf("Welcome, %s (%s)\n", *result.Name, *result.Email)
        if result.PrincipalID != nil {
            fmt.Println("New user provisioned via JIT")
        }
        http.Redirect(w, r, "/dashboard", http.StatusFound)
    })

    // Step 4b: Handle SAML callback
    http.HandleFunc("/sso/saml/callback", func(w http.ResponseWriter, r *http.Request) {
        r.ParseForm()
        result, err := client.SSO.HandleSamlCallback(ctx, grantex.SsoSamlCallbackParams{
            SAMLResponse: r.FormValue("SAMLResponse"),
            RelayState:   r.FormValue("RelayState"),
        })
        if err != nil {
            http.Error(w, err.Error(), 500)
            return
        }

        fmt.Printf("Welcome, %s (%s)\n", *result.Name, *result.Email)
        http.Redirect(w, r, "/dashboard", http.StatusFound)
    })

    log.Fatal(http.ListenAndServe(":8080", nil))
}

Legacy Single-Config Methods

Note: The following methods manage a single OIDC configuration per organization. They are retained for backward compatibility. For new integrations, use the enterprise connection methods above which support multiple IdPs, SAML, and domain-based routing.

Create Config

config, err := client.SSO.CreateConfig(ctx, grantex.CreateSsoConfigParams{
    IssuerURL:    "https://accounts.google.com",
    ClientID:     "your-client-id",
    ClientSecret: "your-client-secret",
    RedirectURI:  "https://myapp.com/sso/callback",
})

Get Config

config, err := client.SSO.GetConfig(ctx)
fmt.Printf("Issuer: %s\n", config.IssuerURL)

Delete Config

err := client.SSO.DeleteConfig(ctx)

result, err := client.SSO.GetLoginURL(ctx, "acme-corp")
// Redirect user to result.AuthorizeURL

Handle Callback

result, err := client.SSO.HandleCallback(ctx, authCode, state)
fmt.Printf("User: %s (%s)\n", *result.Name, *result.Email)

Legacy Types

`SsoConfig`

Field	Type	Description
`IssuerURL`	`string`	OIDC issuer URL
`ClientID`	`string`	OAuth client ID
`RedirectURI`	`string`	Callback URL
`CreatedAt`	`string`	ISO 8601 timestamp
`UpdatedAt`	`string`	ISO 8601 timestamp

​Overview

​Enterprise SSO Connections

​Create Connection

​SAML example

​CreateSsoConnectionParams

​SsoConnection

​List Connections

​Get Connection

​Update Connection

​UpdateSsoConnectionParams

​Delete Connection

​Test Connection

​SsoTestResult

​Enforcement

​Set Enforcement

​SsoEnforcementParams

​SsoEnforcementResponse

​Session Management

​List Sessions

​SsoSession

​Revoke Session

​Enterprise Login Flow

​Get Login URL (enterprise)

​Parameters

​SsoLoginResponse (enterprise)

​Handle OIDC Callback

​SsoOidcCallbackParams

​SsoCallbackResult

​Handle SAML Callback

​SsoSamlCallbackParams

​Handle LDAP Callback

​SsoLdapCallbackParams

​Full Enterprise SSO Flow Example

​Legacy Single-Config Methods

​Create Config

​Get Config

​Delete Config

​Get Login URL (legacy)

​Handle Callback

​Legacy Types

​SsoConfig