Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Split godoc into separate packages #311

Merged
merged 2 commits into from
Nov 10, 2023
Merged

Split godoc into separate packages #311

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b2267f8
Split godoc into separate packages
ewanharris Nov 10, 2023
26e350b
Use TODO instead of Background
ewanharris Nov 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions authentication/doc.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
// Package authentication provides a client for using the Auth0 Authentication API.
//
// # Usage
//
// import (
// "github.com/auth0/go-auth0"
// "github.com/auth0/go-auth0/authentication"
// "github.com/auth0/go-auth0/authentication/database"
// "github.com/auth0/go-auth0/authentication/oauth"
// )
// a, err := authentication.New(
// context.Background(),
ewanharris marked this conversation as resolved.
Show resolved Hide resolved
// domain,
// authentication.WithClientID(id),
// authentication.WithClientSecret(secret), // Optional depending on the grants used
// )
// if err != nil {
// // handle err
// }
// // Now we have an authentication client, we can interact with the Auth0 Authentication API.
// // Sign up a user
// userData := database.SignupRequest{
// Connection: "Username-Password-Authentication",
// Username: "mytestaccount",
// Password: "mypassword",
// Email: "[email protected]",
// }
// createdUser, err := a.Database.Signup(context.Background(), userData)
// if err != nil {
// // handle err
// }
// // Login using OAuth grants
// tokenSet, err := a.OAuth.LoginWithAuthCodeWithPKCE(context.Background(), oauth.LoginWithAuthCodeWithPKCERequest{
// Code: "test-code",
// CodeVerifier: "test-code-verifier",
// }, oauth.IDTokenValidationOptionalVerification{})
//
// if err != nil {
// // handle err
// }
//
// # Configuration
//
// There are several options that can be specified during the creation of a client.
// For a complete list see [Option].
//
// a, err := authentication.New(
// context.Background(),
// domain,
// authentication.WithClientID(id),
// authentication.WithClientSecret(secret), // Optional depending on the grants used
// authentication.WithClockTolerance(10 * time.Second),
// )
package authentication
202 changes: 74 additions & 128 deletions doc.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,129 +1,75 @@
/*
Package auth0 provides a client for using the Auth0 Authentication and Management APIs.

# Authentication

# Usage

import (
"github.com/auth0/go-auth0"
"github.com/auth0/go-auth0/authentication"
"github.com/auth0/go-auth0/authentication/database"
"github.com/auth0/go-auth0/authentication/oauth"
)

Initialize a new client using a context, domain, client ID, and client secret if required.

authAPI, err := authentication.New(
context.Background(),
domain,
authentication.WithClientID(id),
authentication.WithClientSecret(secret), // Optional depending on the grants used
)
if err != nil {
// handle err
}

Now we have an authentication client, we can interact with the Auth0 Authentication API.

// Sign up a user
userData := database.SignupRequest{
Connection: "Username-Password-Authentication",
Username: "mytestaccount",
Password: "mypassword",
Email: "[email protected]",
}

createdUser, err := authAPI.Database.Signup(context.Background(), userData)
if err != nil {
// handle err
}

// Login using OAuth grants
tokenSet, err := authAPI.OAuth.LoginWithAuthCodeWithPKCE(context.Background(), oauth.LoginWithAuthCodeWithPKCERequest{
Code: "test-code",
CodeVerifier: "test-code-verifier",
}, oauth.IDTokenValidationOptionalVerification{})
if err != nil {
// handle err
}

# Management

Usage

import (
"github.com/auth0/go-auth0"
"github.com/auth0/go-auth0/management"
)

Initialize a new client using a domain, client ID and secret.

m, err := management.New(
domain,
management.WithClientCredentials(context.Background(), id, secret),
)
if err != nil {
// handle err
}

Or using a static token.

m, err := management.New(domain, management.WithStaticToken(token))
if err != nil {
// handle err
}

With a management client we can then interact with the Auth0 Management API.

c := &management.Client{
Name: auth0.String("Client Name"),
Description: auth0.String("Long description of client"),
}

err = m.Client.Create(context.Background(), c)
if err != nil {
// handle err
}

## Authentication

The auth0 management package handles authentication by exchanging the client ID and secret
supplied when creating a new management client.

This is handled internally using the https://godoc.org/golang.org/x/oauth2
package.

## Rate Limiting

The auth0 package also handles rate limiting by respecting the `X-Rate-Limit-*`
headers sent by the server.

The amount of time the client waits for the rate limit to be reset is taken from
the `X-Rate-Limit-Reset` header as the amount of seconds to wait.

# Configuration

There are several other options that can be specified during the creation of a
new client.

m, err := management.New(
domain,
management.WithClientCredentials(context.Background(), id, secret),
management.WithDebug(true),
)

## Request Options

As with the global client configuration, fine-grained configuration can be done
on a request basis.

c, err := m.Connection.List(
context.Background(),
management.Page(2),
management.PerPage(10),
management.IncludeFields("id", "name", "options"),
management.Parameter("strategy", "auth0"),
)
*/
// Package auth0 is the Auth0 SDK for Go.
//
// The SDK provides clients that interact with the Auth0 Authentication and Management APIs
// and is split into separate packages as such.
//
// - auth0 - Provides helpers for providing values as pointers.
// - authentication - Provides an Authentication Client for use when interacting with the
// [Authentication API].
// - management - Provides a Management Client for use when interacting with the Auth0
// [Management API].
//
// # Getting Started
//
// Install the SDK using `go get`
//
// go get github.com/auth0/go-auth0
//
// # Authentication
//
// Below is an example of using the Authentication client, for full documentation visit the
// [authentication client docs].
//
// authAPI, err := authentication.New(
// context.Background(),
// domain,
ewanharris marked this conversation as resolved.
Show resolved Hide resolved
// authentication.WithClientID(id),
// authentication.WithClientSecret(secret), // Optional depending on the grants used
// )
// if err != nil {
// // handle err
// }
// // Now we have an authentication client, we can interact with the Auth0 Authentication API.
// // Sign up a user
// userData := database.SignupRequest{
// Connection: "Username-Password-Authentication",
// Username: "mytestaccount",
// Password: "mypassword",
// Email: "[email protected]",
// }
// createdUser, err := authAPI.Database.Signup(context.Background(), userData)
// if err != nil {
// // handle err
// }
//
// # Management
//
// Below is an example of using the Management client, for full documentation visit the
// [management client docs].
//
// import (
// "github.com/auth0/go-auth0"
// "github.com/auth0/go-auth0/management"
// )
// // Initialize a new client using a domain, client ID and secret.
// m, err := management.New(
// domain,
// management.WithClientCredentials(context.Background(), id, secret),
// )
// if err != nil {
// // handle err
// }
// c := &management.Client{
// Name: auth0.String("Client Name"),
// Description: auth0.String("Long description of client"),
// }
// err = m.Client.Create(context.Background(), c)
// if err != nil {
// // handle err
// }
//
// [management client docs]: https://pkg.go.dev/github.com/auth0/go-auth0/management
// [Authentication API]: https://auth0.com/docs/api/authentication
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not super thrilled about having to link to pkg.go.dev directly but I'm not sure the doc links support linking like I want to here (i.e to the top level docs)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would a relative link work?

Screenshot 2023-11-10 at 13 36 29

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately not, we can't use HTML in the docs and the URL support only seems to support full URLs rather than relative.

// [Management API]: https://auth0.com/docs/api/management/v2
// [authentication client docs]: https://pkg.go.dev/github.com/auth0/go-auth0/authentication
package auth0
Loading
Loading