-
Notifications
You must be signed in to change notification settings - Fork 1
Supported Auth Flow Overviews
Neither this documentation nor the library itself are designed to teach you what OAuth 2 is or how it works. You'll need to understand OAuth 2.0 if you want to be successful making OAuth 2 authenticated requests.
The OAuth2RequestSigningHandler and related types are designed to;
- Obtain a token from the server using credentials, if there is no current token or it has expired and can't be refreshed.
- Apply the current token (either newly requested/refreshed, or provided from a previous session) to all requests, to authorise them.
- Refresh the token when it has expired
You setup OAuth2RequestSigningHandler with all the details of the oauth system you're connecting to and then make requests. The library will handle most, sometimes all, of the authorisation & signing required for you.
Most of the work involved in using this library for OAuth 2.0 is in configuring an OAuth2Settings instance.
If you've already obtain a token and/or you want to handle the actual authorisation flow yourself, you can. Assuming you've done the work to obtain a token already, configure your client like this;
var credentials = new SimpleCredentials()
{
Identifier = "your login",
Secret = "your password"
};
// Setup the oauth2 configuration
settings = new OAuth2.OAuth2Settings()
{
// See the existing access token here
AccessToken = new OAuth2.OAuth2Token() { AccessToken = "123", ExpiresIn = 3600, RefreshToken = "456", TokenType = "Bearer", Created = DateTime.Now },
// Provide these details so the token can be refrehsed or replaced if it expires
AccessTokenUrl = new Uri("http://www.someserver.com/Token"),
AuthorizeUrl = new Uri("http://www.someserver/com/authorize),
RedirectUrl = new Uri("http://testsite.com/AuthComplete"),
ClientCredentialProvider = new SimpleCredentialProvider(credentials),
Scope = "your_requested_scope",
GrantType = OAuth2.OAuth2GrantTypes.AuthorizationCode
};
// Create a request signer using the config
var signer = new OAuth2RequestSigningHandler(settings);
// Create a client using the request signer
var client = new System.Net.Http.HttpClient(signer);
// Now requests made with 'client' will be authorised for you.
var result = await client.GetAsync("http://testsite.com/TestEndpoint");
result.EnsureSuccessStatusCode();
This is mainly suited for system to system communications where there is no user present, or where the client needs to access information that is not specific to a particular user. The client presents credentials to the server and receives a token, the token is then used to authorise requests. The token may expire, and a refresh token (if provided by the server) can be used to renew the token. The client credentials grant is also the simplest to implement.
To use the client credentials flow, configure your client like this;
var credentials = new SimpleCredentials()
{
Identifier = "your login",
Secret = "your password"
};
var settings = new OAuth2Settings();
//Set the grant type
settings.GrantType = OAuth2GrantTypes.ClientCredentials;
//Set the credentials to use when requesting a new token
settings.ClientCredentialProvider = new SimpleCredentialProvider(credentials);
//These settings are provided for all auth flows
settings.AccessTokenUrl = new Uri("http://testsite.com/access_token");
settings.AuthorizeUrl = new Uri("http://testsite.com/authorize");
settings.RedirectUrl = new Uri("http://testsite.com/redirect");
// Create a request signer using the config
var signer = new OAuth2RequestSigningHandler(settings);
// Create a client using the request signer
var client = new System.Net.Http.HttpClient(signer);
// Now requests made with 'client' will be authorised for you.
var result = await client.GetAsync("http://testsite.com/TestEndpoint");
result.EnsureSuccessStatusCode();This is the normal authorisation flow used with OAuth 2.0 when a user is present, common in mobile apps and websites. While the library provides support for this flow, the requirement to have the user enter credentials during the flow makes it awkward in many scenarios. It may be better to handle the actual auth flow outside of the library code, then just use library components to sign requests with the token, and refresh it if possible.
To use the client authorization flow, configure your client like this; NB: You'd probably want to use WebAuthenticationBroken (if it's available on your platform) to prompt the user to authorise the token request. Otherwise, you'd like use a TaskCompletionSource with your own dialog.
var credentials = new SimpleCredentials()
{
Identifier = "your login",
Secret = "your password"
};
// Setup the oauth2 configuration
settings = new OAuth2.OAuth2Settings()
{
AccessTokenUrl = new Uri("http://www.someserver.com/Token"),
AuthorizeUrl = new Uri("http://www.someserver/com/authorize),
RedirectUrl = new Uri("http://testsite.com/AuthComplete"),
ClientCredentialProvider = new SimpleCredentialProvider(credentials),
Scope = "your_requested_scope",
GrantType = OAuth2.OAuth2GrantTypes.AuthorizationCode,
RequestSigningMethod = OAuth2HttpRequestSigningMethod.UrlQuery,
// This is the bit that does the 'broken' request for a token
RequestAuthentication = (authorisationUri) =>
{
//TODO: Write your own code here to direct the user to the authorisationUri
//and have them login in. You need to have them enter the auth code returned, or
//obtain it when the user agent redirects to the RedirectUrl. Once you have the
//auth code, return an AuthorisationCodeResponse instance with the details.
//This method is async, so if your code isn't task based, use a
//TaskCompletionSource<AuthorisationCodeResponse> to create a task to return,
//and manage the task status/lifetime.
}
};
// Create a request signer using the config
var signer = new OAuth2RequestSigningHandler(settings);
// Create a client using the request signer
var client = new System.Net.Http.HttpClient(signer);
// Now requests made with 'client' will be authorised for you.
var result = await client.GetAsync("http://testsite.com/TestEndpoint");
result.EnsureSuccessStatusCode();Some 3rd parties have implemented OAuth 2.0 in a way that does not appear to be officially part of the OAuth specification. The authorization_code grant type is still used and the general flow is similar. The main difference is that instead of redirecting the user agent (browser) to a web page for the user to log in, the credentials are posted to the authorisation end point and the server returns a token. This makes it a bastardised combination of the Client Credentials and Authorization Code flows.
To use the broken authorization code flow configure your client the same way as for the Authorization Code Flow but set the RequestAuthentication property of the OAuth2Settings instance to OAuth2RequestSigningHandler.NonInteractiveAuthenticationByJsonResponse. Here's a sample;
var credentials = new SimpleCredentials()
{
Identifier = "your login",
Secret = "your password"
};
// Setup the oauth2 configuration
settings = new OAuth2.OAuth2Settings()
{
AccessTokenUrl = new Uri("http://www.someserver.com/Token"),
AuthorizeUrl = new Uri("http://www.someserver/com/authorize),
RedirectUrl = new Uri("http://testsite.com/AuthComplete"),
ClientCredentialProvider = new SimpleCredentialProvider(credentials),
Scope = "your_requested_scope",
GrantType = OAuth2.OAuth2GrantTypes.AuthorizationCode,
RequestSigningMethod = OAuth2HttpRequestSigningMethod.UrlQuery,
// This is the bit that does the 'broken' request for a token
RequestAuthentication = OAuth2RequestSigningHandler.NonInteractiveAuthenticationByJsonResponse
};
// Create a request signer using the config
var signer = new OAuth2RequestSigningHandler(settings);
// Create a client using the request signer
var client = new System.Net.Http.HttpClient(signer);
// Now requests made with 'client' will be authorised for you.
var result = await client.GetAsync("http://testsite.com/TestEndpoint");
result.EnsureSuccessStatusCode();