Document Legacy Grant Types & Method deprecations (#126)

Legacy flow deprecations Warnings added * Add more information about grant types * Fix typo [skip ci]
auth0 · Jun 26, 2017 · d49b63d · d49b63d
1 parent c32a021
commit d49b63d
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 7 deletions.
diff --git a/Auth0/Authentication.swift b/Auth0/Authentication.swift
@@ -82,7 +82,10 @@ public protocol Authentication: Trackable, Loggable {
 
      - returns: authentication request that will yield Auth0 User Credentials
      - seeAlso: Credentials
+     - warning: this method is deprecated in favor of `login(usernameOrEmail username:, password:, realm:, audience:, scope:)`
+     - requires: Legacy Grant `http://auth0.com/oauth/legacy/grant-type/ro`. Check [our documentation](https://auth0.com/docs/clients/client-grant-types) for more info and how to enable it.
      */
+    @available(*, deprecated, message: "see login(usernameOrEmail username:, password:, realm:, audience:, scope:)")
     // swiftlint:disable:next function_parameter_count
     func login(usernameOrEmail username: String, password: String, multifactorCode: String?, connection: String, scope: String, parameters: [String: Any]) -> Request<Credentials, AuthenticationError>
 
@@ -118,6 +121,7 @@ public protocol Authentication: Trackable, Loggable {
      - parameter scope: scope value requested when authenticating the user.
      - important: This only works if you have the OAuth 2.0 API Authorization flag on
      - returns: authentication request that will yield Auth0 User Credentials
+     - requires: Grant `http://auth0.com/oauth/grant-type/password-realm`. Check [our documentation](https://auth0.com/docs/clients/client-grant-types) for more info and how to enable it.
      */
     func login(usernameOrEmail username: String, password: String, realm: String, audience: String?, scope: String?) -> Request<Credentials, AuthenticationError>
 
@@ -222,7 +226,9 @@ public protocol Authentication: Trackable, Loggable {
      - parameter parameters:   additional parameters sent during authentication
 
      - returns: an authentication request that will yield Auth0 user credentials after creating the user.
+     - requires: Legacy Grant `http://auth0.com/oauth/legacy/grant-type/ro`. Check [our documentation](https://auth0.com/docs/clients/client-grant-types) for more info and how to enable it.
      */
+    @available(*, deprecated, message: "use createUser(email:, username:, password:, connection:, userMetadata:) and then login(usernameOrEmail username:, password:, realm:, audience:, scope:)")
     // swiftlint:disable:next function_parameter_count
     func signUp(email: String, username: String?, password: String, connection: String, userMetadata: [String: Any]?, scope: String, parameters: [String: Any]) -> ConcatRequest<DatabaseUser, Credentials, AuthenticationError>
 
@@ -251,6 +257,7 @@ public protocol Authentication: Trackable, Loggable {
      - parameter parameters: additional authentication parameters added for Web link. Ignored in other types
 
      - returns: a request
+     - requires: Legacy Grant `http://auth0.com/oauth/legacy/grant-type/ro`. Check [our documentation](https://auth0.com/docs/clients/client-grant-types) for more info and how to enable it.
      */
     func startPasswordless(email: String, type: PasswordlessType, connection: String, parameters: [String: Any]) -> Request<Void, AuthenticationError>
 
@@ -278,6 +285,7 @@ public protocol Authentication: Trackable, Loggable {
      - parameter connection:    name of the passwordless connection. By default is 'sms'
 
      - returns: a request
+     - requires: Legacy Grant `http://auth0.com/oauth/legacy/grant-type/ro`. Check [our documentation](https://auth0.com/docs/clients/client-grant-types) for more info and how to enable it.
      */
     func startPasswordless(phoneNumber: String, type: PasswordlessType, connection: String) -> Request<Void, AuthenticationError>
 
@@ -290,12 +298,12 @@ public protocol Authentication: Trackable, Loggable {
         .tokenInfo(token: token)
         .start { print($0) }
      ```
-
+     
      - parameter token: token obtained by authenticating the user
-
+     - warning: this method is deprecated in favor of `userInfo(withAccessToken accessToken:)`
      - returns: a request that will yield token information
      */
-    @available(*, deprecated, message: "see userInfo(token: String)")
+    @available(*, deprecated, message: "see userInfo(withAccessToken accessToken:)")
     func tokenInfo(token: String) -> Request<Profile, AuthenticationError>
 
     /**
@@ -311,7 +319,7 @@ public protocol Authentication: Trackable, Loggable {
      - parameter token: token obtained by authenticating the user
 
      - returns: a request that will yield user information
-     - important: If you are using an OIDC Conformant client please see `userClaimInfo`
+     - warning: for OIDC-conformant clients please use `userInfo(withAccessToken accessToken:)`
      */
     func userInfo(token: String) -> Request<Profile, AuthenticationError>
 
@@ -358,6 +366,8 @@ public protocol Authentication: Trackable, Loggable {
      - parameter parameters: additional parameters sent during authentication
 
      - returns: a request that will yield Auth0 user's credentials
+     - warning: disabled for OIDC-conformant clients, an alternative will be added in a future release
+     - requires: Legacy Grant `http://auth0.com/oauth/legacy/grant-type/access_token`. Check [our documentation](https://auth0.com/docs/clients/client-grant-types) for more info and how to enable it.
      */
     func loginSocial(token: String, connection: String, scope: String, parameters: [String: Any]) -> Request<Credentials, AuthenticationError>
 
@@ -374,7 +384,7 @@ public protocol Authentication: Trackable, Loggable {
      - parameter parameters: request parameters
 
      - returns: a request that will yield Auth0 user's credentials
-     - seeAlso: Authentication#exchangeCode(codeVerifier:redirectURI:) for PKCE
+     - seeAlso: exchangeCode(codeVerifier:, redirectURI:) for PKCE
      */
     func tokenExchange(withParameters parameters: [String: Any]) -> Request<Credentials, AuthenticationError>
 
@@ -525,6 +535,7 @@ public extension Authentication {
 
      - returns: authentication request that will yield Auth0 User Credentials
      - seeAlso: Credentials
+     - requires: Legacy Grant `http://auth0.com/oauth/legacy/grant-type/ro`. Check [our documentation](https://auth0.com/docs/clients/client-grant-types) for more info and how to enable it.
      */
     public func login(usernameOrEmail username: String, password: String, multifactorCode: String? = nil, connection: String, scope: String = "openid", parameters: [String: Any] = [:]) -> Request<Credentials, AuthenticationError> {
         return self.login(usernameOrEmail: username, password: password, multifactorCode: multifactorCode, connection: connection, scope: scope, parameters: parameters)
@@ -561,6 +572,7 @@ public extension Authentication {
      - parameter audience: API Identifier that the client is requesting access to.
      - parameter scope: scope value requested when authenticating the user.
      - Returns: authentication request that will yield Auth0 User Credentials
+     - requires: Grant `http://auth0.com/oauth/grant-type/password-realm`. Check [our documentation](https://auth0.com/docs/clients/client-grant-types) for more info and how to enable it.
      */
     public func login(usernameOrEmail username: String, password: String, realm: String, audience: String? = nil, scope: String? = nil) -> Request<Credentials, AuthenticationError> {
         return self.login(usernameOrEmail: username, password: password, realm: realm, audience: audience, scope: scope)
@@ -652,6 +664,7 @@ public extension Authentication {
      - parameter parameters:   additional parameters sent during authentication
 
      - returns: an authentication request that will yield Auth0 user credentials after creating the user.
+     - requires: Legacy Grant `http://auth0.com/oauth/legacy/grant-type/ro`. Check [our documentation](https://auth0.com/docs/clients/client-grant-types) for more info and how to enable it.
      */
     public func signUp(email: String, username: String? = nil, password: String, connection: String, userMetadata: [String: Any]? = nil, scope: String = "openid", parameters: [String: Any] = [:]) -> ConcatRequest<DatabaseUser, Credentials, AuthenticationError> {
         return self.signUp(email: email, username: username, password: password, connection: connection, userMetadata: userMetadata, scope: scope, parameters: parameters)
@@ -740,6 +753,7 @@ public extension Authentication {
      - parameter parameters: additional parameters sent during authentication
 
      - returns: a request that will yield Auth0 user's credentials
+     - requires: Legacy Grant `http://auth0.com/oauth/legacy/grant-type/access_token`. Check [our documentation](https://auth0.com/docs/clients/client-grant-types) for more info and how to enable it.
      */
     public func loginSocial(token: String, connection: String, scope: String = "openid", parameters: [String: Any] = [:]) -> Request<Credentials, AuthenticationError> {
         return self.loginSocial(token: token, connection: connection, scope: scope, parameters: parameters)
@@ -762,7 +776,7 @@ public extension Authentication {
         .start { print($0) }
      ```
 
-     If you are not using OAuth 2.0 API Authorization please use `delegation(parameters:)`
+     - precondition: if you are not using OAuth 2.0 API Authorization please use `delegation(parameters:)`
 
      - parameter refreshToken: the client's refresh token obtained on auth
      - parameter scope: scopes to request for the new tokens. By default is nil which will ask for the same ones requested during Auth.

diff --git a/README.md b/README.md
@@ -194,7 +194,7 @@ credentialsManager.credentials { error, credentials in
 ### Authentication API (iOS / macOS / tvOS)
 
 The Authentication API exposes AuthN/AuthZ functionality of Auth0, as well as the supported identity protocols like OpenID Connect, OAuth 2.0, and SAML. 
-We recommend using our Hosted Login Page but if you wish to build your own UI you can use our API endpoints to do so. However some Auth flows (Grant types) are disable by default so you will need to enable them via your Auth0 Dashboard as explained in [this guide](https://auth0.com/docs/clients/client-grant-types#edit-available-grant_types).
+We recommend using our Hosted Login Page but if you wish to build your own UI you can use our API endpoints to do so. However some Auth flows (Grant types) are disabled by default so you will need to enable them via your Auth0 Dashboard as explained in [this guide](https://auth0.com/docs/clients/client-grant-types#edit-available-grant_types).
 
 These are the required Grant Types that needs to be enabled in your client: