Setting Up Vault as an Identity Provider: A Fresh Approach

User Authentication with HashiCorp Vault: Simplifying and Securing Your Application

When developing an application, user authentication (AuthN) is a crucial feature that can often be complex and prone to errors if implemented from scratch. Instead of building your own AuthN system, which involves enforcing password complexity rules, implementing password checking, and enforcing failed login attempt policies, you can delegate this task to a specialized platform like HashiCorp Vault. This not only simplifies the process but also enhances security for your business and customers by leveraging Vault’s capabilities as an identity provider (IdP).

In this comprehensive guide, we’ll explore how to set up HashiCorp Vault as an OpenID Connect (OIDC) IdP for your applications. This will allow your organization to manage secrets and identity servers through one platform, creating a standardized security library.

Understanding OIDC

OpenID Connect (OIDC) is a widely adopted standard for user authentication. Since 2021, HashiCorp Vault has supported acting as an OIDC IdP. Here’s a high-level overview of how OIDC works:

1. User Interaction: The user navigates to a web or mobile application, known as the relying party (RP). An RP is an application that delegates user authentication to an external IdP.
2. Credential Submission: The user enters their credentials, typically a username and password.
3. AuthN Request: The RP sends this information as an AuthN request to the IdP.
4. Authentication: The IdP checks the credentials.
5. Token Issuance: If the credentials are correct, the IdP responds with an access token.
6. Request Submission: The authenticated user can now submit requests to the application with the access token attached.

   The access token is usually a signed JSON Web Token (JWT), which the RP can verify to confirm its authenticity. IdPs often provide a token verification endpoint or publish JSON Web Key Sets (JWKS) for this purpose.

   Vault as an OIDC Provider
   

   Using Vault as an OIDC provider means that RPs can delegate AuthN to Vault, as outlined in the OIDC workflow. Vault’s responsibilities include authenticating users, issuing signed JWTs, and verifying JWT signatures.

   Configuring Vault as an OIDC Provider
   

   To set up Vault as an OIDC provider, follow these steps:

7. Enable Auth Method: Enable the auth method, such as userpass, for user authentication.

   hcl<br /> resource "vault_auth_backend" "userpass" {<br /> type = "userpass"<br /> }<br />

8. Create Signing Key: Configure a key to sign JWTs.

   hcl<br /> resource "vault_identity_oidc_key" "oidc_key" {<br /> name = "my-key"<br /> rotation_period = 3600<br /> algorithm = "RS256"<br /> allowed_client_ids = ["*"]<br /> verification_ttl = 7200<br /> }<br />

9. Create OIDC Provider: Minimal configuration is needed.

   hcl<br /> resource "vault_identity_oidc" "oidc" {}<br />

10. Create OIDC Role: Define an OIDC role for JWT creation.

    hcl<br /> resource "vault_identity_oidc_role" "role" {<br /> key = vault_identity_oidc_key.oidc_key.name<br /> name = "my-role"<br /> template = <<EOF<br /> {<br /> "email": {{identity.entity.metadata.email}},<br /> "username": {{identity.entity.name}}<br /> }<br /> EOF<br /> ttl = 3600<br /> }<br />

11. Create Policy: Allow authenticated users to request a signed JWT.

    hcl<br /> resource "vault_policy" "jwt" {<br /> name = "jwt"<br /> policy = <<EOF<br /> path "/identity/oidc/token/my-role" {<br /> capabilities = ["read"]<br /> }<br /> EOF<br /> }<br />

    Application Development as a Relying Party
    

    Building an application involves two main sections: user registration and authentication.

    User Registration
    

    Onboarding new users to Vault requires the following steps:

12. Create User: In the userpass auth method.
13. Create Entity: In the Identity secrets engine.
14. Create Alias: Tying the entity and user together.
15. Create OIDC Assignment: For identity issuance by the OIDC provider.

    Using Go, you can implement these steps as follows:

16. Create User:

    go<br /> func createUser(vc *vault.Client, userName, password string) error {<br /> ctx := context.Background()<br /> userCreateRequest := schema.UserpassWriteUserRequest{Password: password}<br /> _, err := vc.Auth.UserpassWriteUser(ctx, userName, userCreateRequest)<br /> if err != nil {<br /> log.Error(err)<br /> return err<br /> }<br /> return nil<br /> }<br />

17. Create Entity:

    go<br /> func createEntity(vc *vault.Client, userName, email string) (interface{}, error) {<br /> ctx := context.Background()<br /> metadata := map[string]interface{}{"email": email}<br /> entityCreateRequest := schema.EntityCreateRequest{<br /> Disabled: false,<br /> Metadata: metadata,<br /> Name: userName,<br /> Policies: []string{"jwt"},<br /> }<br /> entityResult, err := vc.Identity.EntityCreate(ctx, entityCreateRequest)<br /> if err != nil {<br /> log.Error(err)<br /> return nil, err<br /> }<br /> return entityResult.Data, nil<br /> }<br />

18. Create Alias:

    go<br /> func createAlias(vc *vault.Client, canonicalId, userName, mountAccessor string) (interface{}, error) {<br /> ctx := context.Background()<br /> aliasRequest := schema.AliasCreateRequest{<br /> CanonicalId: canonicalId,<br /> MountAccessor: mountAccessor,<br /> Name: userName,<br /> }<br /> aliasResponse, err := vc.Identity.AliasCreate(ctx, aliasRequest)<br /> if err != nil {<br /> log.Error(err)<br /> return nil, err<br /> }<br /> return aliasResponse.Data, nil<br /> }<br />

19. Create Assignment:

    go<br /> func createAssignment(vc *vault.Client, entityId, name string) error {<br /> ctx := context.Background()<br /> entityIdList := []string{entityId}<br /> assignmentRequest := schema.OidcWriteAssignmentRequest{<br /> EntityIds: entityIdList,<br /> GroupIds: nil,<br /> }<br /> _, err := vc.Identity.OidcWriteAssignment(ctx, name, assignmentRequest)<br /> if err != nil {<br /> log.Error(err)<br /> return err<br /> }<br /> return nil<br /> }<br />

20. Unified Workflow:

    go<br /> func UserCreate(userName, password, emailAddr string) map[string]string {<br /> vc := NewClient(os.Getenv("VAULT_ADDR"), os.Getenv("VAULT_TOKEN"))<br /> mountAccessor := os.Getenv("MOUNT_ACCESSOR_ID")<br /> <br /> createUser(&vc, userName, password)<br /> entityResult, err := createEntity(&vc, userName, emailAddr)<br /> if err != nil {<br /> log.Error(err)<br /> return nil<br /> }<br /> <br /> resultMap, ok := entityResult.(map[string]interface{})<br /> if !ok {<br /> log.Error("Unexpected type for entity result")<br /> return nil<br /> }<br /> <br /> EntityIdValue, ok := resultMap["id"].(string)<br /> if !ok {<br /> log.Error("ID is not a string or not found in entity result")<br /> return nil<br /> }<br /> <br /> aliasResult, err := createAlias(&vc, EntityIdValue, userName, mountAccessor)<br /> if err != nil {<br /> log.Error(err)<br /> return nil<br /> }<br /> <br /> aliasResultMap, ok := aliasResult.(map[string]interface{})<br /> if !ok {<br /> log.Error("Unexpected type for alias result")<br /> return nil<br /> }<br /> <br /> aliasId, ok := aliasResultMap["id"].(string)<br /> if !ok {<br /> log.Error("Alias ID is not a string or not found")<br /> return nil<br /> }<br /> <br /> err = createAssignment(&vc, EntityIdValue, userName)<br /> if err != nil {<br /> log.Error(err)<br /> return nil<br /> }<br /> <br /> finalResult := make(map[string]string)<br /> finalResult["Username"] = userName<br /> finalResult["Entity ID"] = EntityIdValue<br /> finalResult["Alias ID"] = aliasId<br /> <br /> return finalResult<br /> }<br />

    User Authentication
    

    Authenticating users involves two steps: submitting credentials and generating a JWT.

21. Authenticate User:

    go<br /> func userpassAuth(userName, password string) (string, error) {<br /> ctx := context.Background()<br /> vc := NewClient(os.Getenv("VAULT_ADDR"), "")<br /> loginRequest := schema.UserpassLoginRequest{Password: password}<br /> vaultToken, err := vc.Auth.UserpassLogin(ctx, userName, loginRequest)<br /> if err != nil {<br /> return "", err<br /> }<br /> return vaultToken.Auth.ClientToken, nil<br /> }<br />

22. Generate JWT:

    go<br /> func generateToken(vc *vault.Client, roleName string) (interface{}, error) {<br /> ctx := context.Background()<br /> tokenResult, err := vc.Identity.OidcGenerateToken(ctx, roleName)<br /> if err != nil {<br /> log.Error(err)<br /> return nil, err<br /> }<br /> return tokenResult.Data, nil<br /> }<br />

23. Unified Workflow:

    go<br /> func UserAuthenticate(userName, password string) (string, error) {<br /> vaultToken, err := userpassAuth(userName, password)<br /> if err != nil {<br /> log.Error(err)<br /> return "", err<br /> }<br /> <br /> authenticatedVc := NewClient(os.Getenv("VAULT_ADDR"), vaultToken)<br /> jwt, err := generateToken(&authenticatedVc, "my-role")<br /> if err != nil {<br /> log.Error(err)<br /> return "", err<br /> }<br /> <br /> jwtMap, ok := jwt.(map[string]interface{})<br /> if !ok {<br /> log.Error("JWT unexpected type")<br /> return "", nil<br /> }<br /> <br /> jsonWebToken, ok := jwtMap["token"].(string)<br /> if !ok {<br /> log.Error("JWT token not found or not a string")<br /> return "", nil<br /> }<br /> <br /> return jsonWebToken, nil<br /> }<br />

    Validating a JWT
    

    JWT validation ensures the token’s integrity and authenticity. Here’s a function for token validation:

    go<br /> func ValidateToken(token string) (bool, error) {<br /> vc := NewClient(os.Getenv("VAULT_ADDR"), os.Getenv("VAULT_TOKEN"))<br /> ctx := context.Background()<br /> clientId := os.Getenv("OIDC_CLIENT_ID")<br /> <br /> validateRequest := schema.OidcIntrospectRequest{<br /> ClientId: clientId,<br /> Token: token,<br /> }<br /> <br /> validate, err := vc.Identity.OidcIntrospect(ctx, validateRequest)<br /> if err != nil {<br /> log.Error(err)<br /> return false, err<br /> }<br /> <br /> validateMap, ok := validate.Data["active"].(bool)<br /> if !ok {<br /> log.Error("JWT not valid")<br /> return false, nil<br /> }<br /> <br /> var response bool<br /> switch validateMap {<br /> case true:<br /> response = true<br /> case false:<br /> response = false<br /> default:<br /> response = false<br /> }<br /> <br /> return response, nil<br /> }<br />

    Recommendations and Resources
    

    When configuring Vault as an IdP, it’s best practice to write output values in your Terraform code for the mount accessor ID of the userpass auth method and the client ID of the OIDC role. This Terraform module can be used to configure Vault as an OIDC provider.

    When setting up the RP application and building a user signup workflow, consider the following:

    • Use multithreading or Goroutines for handling multiple requests in parallel.
    • Use environment variables for static configuration values.
    • Ensure the Vault cluster is close to the application to reduce latency.
    • Plan for increased latency due to multiple calls to Vault.

      To try this for your application, sign up for a HashiCorp Cloud Platform account and deploy a managed dedicated Vault Cluster in minutes. You can also integrate Vault with HashiCorp Boundary for secure remote access by following this tutorial.

      For more details and to access the original post, visit the HashiCorp website.

For more Information, Refer to this article.