microsoft-authentication-library-for-go

module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 20, 2023 License: MIT

README

Microsoft Authentication Library (MSAL) for Go

MSAL for Go is a new addition to the MSAL family of libraries, has been made available in production ready preview to gauge customer interest and to gather feedback from the community. We welcome all contributors (see CONTRIBUTING.md) to help us grow our list of supported MSAL SDKs.

The Microsoft Authentication Library (MSAL) for Go is part of the Microsoft identity platform for developers (formerly named Azure AD) v2.0. It allows you to sign in users or apps with Microsoft identities (Azure AD and Microsoft Accounts) and obtain tokens to call Microsoft APIs such as Microsoft Graph or your own APIs registered with the Microsoft identity platform. It is built using industry standard OAuth2 and OpenID Connect protocols.

The latest code resides in the dev branch.

Quick links:

Getting Started GoDoc Wiki Samples Support Feedback

Build Status

Go

Installation

Setting up Go

To install Go, visit this link.

Installing MSAL Go

go get -u github.com/AzureAD/microsoft-authentication-library-for-go/

Usage

Before using MSAL Go, you will need to register your application with the Microsoft identity platform.

Public Surface

The Public API of the library can be found in the following directories under apps.

apps/ - Contains all our code
  confidential/ - The confidential application API
  public/ - The public application API
  cache/ - The cache interface that can be implemented to provide persistence cache storage of credentials

Acquiring tokens with MSAL Go follows this general three step pattern. There might be some slight differences for other token acquisition flows. Here is a basic example:

  1. MSAL separates public and confidential client applications. So, you would create an instance of a PublicClientApplication and ConfidentialClientApplication and use this throughout the lifetime of your application.

    • Initializing a public client:
    publicClientApp, err := public.New("client_id", public.WithAuthority("https://login.microsoft.com/Enter_The_Tenant_Name_Here"))
    
    • Initializing a confidential client:
    // Initializing the client credential
    cred, err := confidential.NewCredFromSecret("client_secret")
    if err != nil {
        return nil, fmt.Errorf("could not create a cred from a secret: %w", err)
    }
    confidentialClientApp, err := confidential.New("client_id", cred, confidential.WithAuthority("https://login.microsoft.com/Enter_The_Tenant_Name_Here"))
    
  2. MSAL comes packaged with an in-memory cache. Utilizing the cache is optional, but we would highly recommend it.

    var userAccount public.Account
    accounts := publicClientApp.Accounts()
    if len(accounts) > 0 {
        // Assuming the user wanted the first account
        userAccount = accounts[0]
        // found a cached account, now see if an applicable token has been cached
        result, err := publicClientApp.AcquireTokenSilent(context.Background(), []string{"your_scope"}, public.WithSilentAccount(userAccount))
        accessToken := result.AccessToken
    }
    
  3. If there is no suitable token in the cache, or you choose to skip this step, now we can send a request to AAD to obtain a token.

    result, err := publicClientApp.AcquireToken"ByOneofTheActualMethods"([]string{"your_scope"}, ...(other parameters depending on the function))
    if err != nil {
        log.Fatal(err)
    }
    accessToken := result.AccessToken
    

You can view the dev apps on how to use MSAL Go with various application types in various scenarios. For more detailed information, please refer to the wiki.

Releases

The list of releases

Roadmap

This is a preview library. Details of the roadmap will come soon in the wiki pages, along with release notes.

Community Help and Support

We use Stack Overflow to work with the community on supporting Azure Active Directory and its SDKs, including this one! We highly recommend you ask your questions on Stack Overflow (we're all on there!) Also browse existing issues to see if someone has had your question before. Please use the "msal" tag when asking your questions.

If you find and bug or have a feature request, please raise the issue on GitHub Issues.

Submit Feedback

We'd like your thoughts on this library. Please complete this short survey.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Security Library

This library controls how users sign-in and access services. We recommend you always take the latest version of our library in your app when possible. We use semantic versioning so you can control the risk associated with updating your app. As an example, always downloading the latest minor version number (e.g. x.y.x) ensures you get the latest security and feature enhancements but our API surface remains the same. You can always see the latest version and release notes under the Releases tab of GitHub.

Security Reporting

If you find a security issue with our libraries or services please report it to secure@microsoft.com with as much detail as possible. Your submission may be eligible for a bounty through the Microsoft Bounty program. Please do not post security issues to GitHub Issues or any other public site. We will contact you shortly upon receiving the information. We encourage you to get notifications of when security incidents occur by visiting this page and subscribing to Security Advisory Alerts.

Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License (the "License").

Directories

Path Synopsis
apps
cache
Package cache allows third parties to implement external storage for caching token data for distributed systems or multiple local applications access.
Package cache allows third parties to implement external storage for caching token data for distributed systems or multiple local applications access.
confidential
Package confidential provides a client for authentication of "confidential" applications.
Package confidential provides a client for authentication of "confidential" applications.
internal/base
Package base contains a "Base" client that is used by the external public.Client and confidential.Client.
Package base contains a "Base" client that is used by the external public.Client and confidential.Client.
internal/base/internal/storage
Package storage holds all cached token information for MSAL.
Package storage holds all cached token information for MSAL.
internal/exported
package exported contains internal types that are re-exported from a public package
package exported contains internal types that are re-exported from a public package
internal/json
Package json provide functions for marshalling an unmarshalling types to JSON.
Package json provide functions for marshalling an unmarshalling types to JSON.
internal/json/types/time
Package time provides for custom types to translate time from JSON and other formats into time.Time objects.
Package time provides for custom types to translate time from JSON and other formats into time.Time objects.
internal/local
Package local contains a local HTTP server used with interactive authentication.
Package local contains a local HTTP server used with interactive authentication.
internal/oauth/ops
Package ops provides operations to various backend services using REST clients.
Package ops provides operations to various backend services using REST clients.
internal/oauth/ops/accesstokens
Package accesstokens exposes a REST client for querying backend systems to get various types of access tokens (oauth) for use in authentication.
Package accesstokens exposes a REST client for querying backend systems to get various types of access tokens (oauth) for use in authentication.
internal/oauth/ops/internal/comm
Package comm provides helpers for communicating with HTTP backends.
Package comm provides helpers for communicating with HTTP backends.
internal/oauth/ops/internal/grant
Package grant holds types of grants issued by authorization services.
Package grant holds types of grants issued by authorization services.
internal/oauth/ops/wstrust
Package wstrust provides a client for communicating with a WSTrust (https://en.wikipedia.org/wiki/WS-Trust#:~:text=WS%2DTrust%20is%20a%20WS,in%20a%20secure%20message%20exchange.) for the purposes of extracting metadata from the service.
Package wstrust provides a client for communicating with a WSTrust (https://en.wikipedia.org/wiki/WS-Trust#:~:text=WS%2DTrust%20is%20a%20WS,in%20a%20secure%20message%20exchange.) for the purposes of extracting metadata from the service.
internal/version
Package version keeps the version number of the client package.
Package version keeps the version number of the client package.
public
Package public provides a client for authentication of "public" applications.
Package public provides a client for authentication of "public" applications.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL