-
Notifications
You must be signed in to change notification settings - Fork 55
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.
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
Split godoc into separate packages #311
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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.TODO(), | ||
| // 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.TODO(), userData) | ||
| // if err != nil { | ||
| // // handle err | ||
| // } | ||
| // // Login using OAuth grants | ||
| // tokenSet, err := a.OAuth.LoginWithAuthCodeWithPKCE(context.TODO(), 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.TODO(), | ||
| // domain, | ||
| // authentication.WithClientID(id), | ||
| // authentication.WithClientSecret(secret), // Optional depending on the grants used | ||
| // authentication.WithClockTolerance(10 * time.Second), | ||
| // ) | ||
| package authentication |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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.TODO(), | ||
| // 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.TODO(), 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.TODO(), 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.TODO(), 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 | ||
| // [Management API]: https://auth0.com/docs/api/management/v2 | ||
| // [authentication client docs]: https://pkg.go.dev/github.com/auth0/go-auth0/authentication | ||
| package auth0 | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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)
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.