# BITAuthenticator Class Reference

Inherits from | BITHockeyBaseManager : NSObject
Declared in | BITAuthenticator.h

## Overview

Identify and authenticate users of Ad-Hoc or Enterprise builds

`BITAuthenticator` serves 2 purposes:

1. Identifying who is running your Ad-Hoc or Enterprise builds `BITAuthenticator` provides an identifier for the rest of the HockeySDK to work with, e.g. in-app update checks and crash reports.

2. Optional regular checking if an identified user is still allowed to run this application. The `BITAuthenticator` can be used to make sure only users who are testers of your app are allowed to run it.

This module automatically disables itself when running in an App Store build by default!

Warning: It is mandatory to call `authenticateInstallation` somewhen after calling `[[BITHockeyManager sharedHockeyManager] startManager]` or fully customize the identification and validation workflow yourself. If your app shows a modal view on startup, make sure to call `authenticateInstallation` either once your modal view is fully presented (e.g. its `viewDidLoad:` method is processed) or once your modal view is dismissed.

## Tasks

### Configuration

- `identificationType` property
- `restrictApplicationUsage` property
- `restrictionEnforcementFrequency` property
- `authenticationSecret` property
- `delegate` property

### Device based identification

- `webpageURL` property
- `– deviceAuthenticationURL`
- `urlScheme` property
- `– handleOpenURL:sourceApplication:annotation:`

### Authentication

- `– authenticateInstallation`
- `– identifyWithCompletion:`
- `identified` property
- `– validateWithCompletion:`
- `validated` property
- `– cleanupInternalStorage`
- `– publicInstallationIdentifier`

## Properties

### authenticationSecret

The authentication secret from HockeyApp. To find the right secret, click on your app on the HockeyApp dashboard, then on Show next to “Secret:”.

`@property (nonatomic, copy) NSString *authenticationSecret`

#### Discussion

This is only needed if `identificationType` is set to `BITAuthenticatorIdentificationTypeHockeyAppEmail`

#### See Also

- `

  @property identificationType

  `

#### Declared In

`BITAuthenticator.h`

### delegate

Delegate that can be used to do any last minute configurations on the presented viewController.

`@property (nonatomic, weak) id<BITAuthenticatorDelegate> delegate`

#### See Also

- `

  BITAuthenticatorDelegate

  `

#### Declared In

`BITAuthenticator.h`

### identificationType

Defines the identification mechanism to be used

`@property (nonatomic, assign) BITAuthenticatorIdentificationType identificationType`

#### Discussion

Default: `BITAuthenticatorIdentificationTypeAnonymous`

#### See Also

- `

  BITAuthenticatorIdentificationType

  `

#### Declared In

`BITAuthenticator.h`

### identified

Returns YES if this app is identified according to the setting in `identificationType`.

`@property (nonatomic, assign, readonly, getter=isIdentified) BOOL identified`

#### Discussion

Since the identification process is done asynchronously (contacting the server), you need to observe the value change via KVO.

#### See Also

- `

  @property identificationType

  `

#### Declared In

`BITAuthenticator.h`

### restrictApplicationUsage

Enables or disables checking if the user is allowed to run this app

`@property (nonatomic, assign) BOOL restrictApplicationUsage`

#### Discussion

If disabled, the Authenticator never validates, besides initial identification, if the user is allowed to run this application.

If enabled, the Authenticator checks depending on `restrictionEnforcementFrequency` if the user is allowed to use this application.

Enabling this property and setting `identificationType` to `BITAuthenticatorIdentificationTypeHockeyAppEmail`, `BITAuthenticatorIdentificationTypeHockeyAppUser` or `BITAuthenticatorIdentificationTypeWebAuth` also allows to remove access for users by removing them from the app’s users list on HockeyApp.

Default: `NO`

Warning: if `identificationType` is set to `BITAuthenticatorIdentificationTypeAnonymous`, this property has no effect.

#### See Also

- `

  BITAuthenticatorIdentificationType

  `
- `

  @property restrictionEnforcementFrequency

  `

#### Declared In

`BITAuthenticator.h`

### restrictionEnforcementFrequency

Defines how often the BITAuthenticator checks if the user is allowed to run this application

`@property (nonatomic, assign) BITAuthenticatorAppRestrictionEnforcementFrequency restrictionEnforcementFrequency`

#### Discussion

This requires `restrictApplicationUsage` to be enabled.

Default: `BITAuthenticatorAppRestrictionEnforcementOnFirstLaunch`

#### See Also

- `

  BITAuthenticatorAppRestrictionEnforcementFrequency

  `
- `

  @property restrictApplicationUsage

  `

#### Declared In

`BITAuthenticator.h`

### urlScheme

The url-scheme used to idenfify via `BITAuthenticatorIdentificationTypeDevice`

`@property (nonatomic, strong) NSString *urlScheme`

#### Discussion

Please make sure that the URL scheme is unique and not shared with other apps.

If set to nil, the default scheme is used which is `ha<APP_ID>`.

#### See Also

- `

  @property identificationType

  `
- `

  - handleOpenURL:sourceApplication:annotation:

  `

#### Declared In

`BITAuthenticator.h`

### validated

Indicates if this installation is validated.

`@property (nonatomic, assign, readonly, getter=isValidated) BOOL validated`

#### Declared In

`BITAuthenticator.h`

### webpageURL

The baseURL of the webpage the user is redirected to if `identificationType` is set to `BITAuthenticatorIdentificationTypeDevice`; defaults to https://rink.hockeyapp.net.

`@property (nonatomic, strong) NSURL *webpageURL`

#### See Also

- `

  @property identificationType

  `

#### Declared In

`BITAuthenticator.h`

## Instance Methods

### authenticateInstallation

Invoked automatic identification and validation

`- (void)authenticateInstallation`

#### Discussion

If the `BITAuthenticator` is in automatic mode this will initiate identifying the current user according to the type specified in `identificationType` and validate if the identified user is allowed to run this application.

If the user is not yet identified it will present a modal view asking the user to provide the required information.

If your app provides it’s own startup modal screen, e.g. a guide or a login, then you might either call this method once that UI is fully presented or once the user e.g. did actually login already.

Warning: You need to call this method in your code even if automatic mode is enabled!

#### See Also

- `

  @property identificationType

  `

#### Declared In

`BITAuthenticator.h`

### cleanupInternalStorage

Removes all previously stored authentication tokens, UDIDs, etc.

`- (void)cleanupInternalStorage`

#### Declared In

`BITAuthenticator.h`

### deviceAuthenticationURL

URL to query the device’s id via external webpage Built with the baseURL set in `webpageURL`.

`- (NSURL *)deviceAuthenticationURL`

#### Declared In

`BITAuthenticator.h`

### handleOpenURL:sourceApplication:annotation:

Should be used by the appdelegate to forward handle application:openURL:sourceApplication:annotation: calls.

`- (BOOL)handleOpenURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation`

#### Parameters

url

  Param `url` that was passed to the app

sourceApplication

  Param `sourceApplication` that was passed to the app

annotation

  Param `annotation` that was passed to the app

#### Return Value

YES if the URL request was handled, NO if the URL could not be handled/identified.

#### Discussion

This is required if `identificationType` is set to `BITAuthenticatorIdentificationTypeDevice`. Your app needs to implement the default `ha<APP_ID>` URL scheme or register its own scheme via `urlScheme`. BITAuthenticator checks if the given URL is actually meant to be parsed by it and will return NO if it doesn’t think so. It does this by checking the ‘host’-part of the URL to be ‘authorize’, as well as checking the protocol part. Please make sure that if you’re using a custom URL scheme, it does not conflict with BITAuthenticator’s. If BITAuthenticator thinks the URL was meant to be an authorization URL, but could not find a valid token, it will reset the stored identification token and state.

Sample usage (in AppDelegate):

    - (BOOL)application:(UIApplication *)application
                openURL:(NSURL *)url
      sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
      if ([[BITHockeyManager sharedHockeyManager].authenticator handleOpenURL:url
                                                            sourceApplication:sourceApplication
                                                                   annotation:annotation]) {
        return YES;
      } else {
        //do your own URL handling, return appropriate value
      }
      return NO;
    }

#### See Also

- `

  @property identificationType

  `
- `

  @property urlScheme

  `

#### Declared In

`BITAuthenticator.h`

### identifyWithCompletion:

Identifies the user according to the type specified in `identificationType`.

`- (void)identifyWithCompletion:(void ( ^ ) ( BOOL identified , NSError *error ))completion`

#### Parameters

completion

  Block being executed once identification completed

#### Discussion

If the `BITAuthenticator` is in manual mode, it’s your responsibility to call this method. Depending on the `identificationType`, this method might present a viewController to let the user enter his/her credentials.

If the Authenticator is in auto-mode, this is called by the authenticator itself once needed.

#### See Also

- `

  @property identificationType

  `
- `

  - authenticateInstallation

  `
- `

  - validateWithCompletion:

  `

#### Declared In

`BITAuthenticator.h`

### publicInstallationIdentifier

Returns different values depending on `identificationType`. This can be used by the application to identify the user.

`- (NSString *)publicInstallationIdentifier`

#### See Also

- `

  @property identificationType

  `

#### Declared In

`BITAuthenticator.h`

### validateWithCompletion:

Validates if the identified user is allowed to run this application. This checks with the HockeyApp backend and calls the completion-block once completed.

`- (void)validateWithCompletion:(void ( ^ ) ( BOOL validated , NSError *error ))completion`

#### Parameters

completion

  Block being executed once validation completed

#### Discussion

If the `BITAuthenticator` is in manual mode, it’s your responsibility to call this method. If the application is not yet identified, validation is not possible and the completion-block is called with an error set.

If the `BITAuthenticator` is in auto-mode, this is called by the authenticator itself once needed.

#### See Also

- `

  @property identificationType

  `
- `

  - authenticateInstallation

  `
- `

  - identifyWithCompletion:

  `

#### Declared In

`BITAuthenticator.h`